Using SwaggerUI to implement API online documentation in Golang

Using SwaggerUI to implement API online documentation in Golang

With the emergence of modern application architecture, API (Application Programming Interface) has become the basic component of modern Web applications. As the number of APIs continues to increase, writing and maintaining API documentation has become a tedious task. Therefore, it is very necessary to simplify the writing and maintenance process of API documentation. Swagger is a popular solution that provides a powerful documentation tool for Web APIs. This article will introduce how to use SwaggerUI to implement API online documentation in Golang.

Swagger Introduction

Swagger is a set of open source API building tools that can help developers design, build, document and test RESTful APIs. It includes multiple tools such as Swagger Editor, Swagger UI and Swagger Codegen.

Among them, Swagger Editor is a web browser-based editor that can help developers write and edit Swagger specifications. Swagger UI is a tool that can render Swagger specifications into API documents. Swagger Codegen can Automatically generate client-side and server-side API code.

Using SwaggerUI to implement API online documentation in Golang

Golang is a very popular programming language. Its advantage is that it has high concurrency performance and low overhead. It uses lightweight threads called Goroutines to handle concurrency and supports automatic memory recycling and garbage collection. In Golang, you can use the go-swagger library to implement API online documentation.

1. Install Swagger

First, you need to install Swagger, which can be installed through the following command:

$ brew tap go-swagger/go-swagger
$ brew install go-swagger

2. Initialize a Golang project

Next, you need to initialize a Golang project on your local computer. Created a Golang project named Go-Swagger-API on your local computer using the following command:

$ mkdir Go-Swagger-API 
$ cd Go-Swagger-API 
$ go mod init Go-Swagger-API 

3. Create API Definition

In order to create an API definition, you need Create a YAML file and define the API settings in it. In this example, you can create a file named pets.yaml and add the following code in it:

swagger: "2.0"
info:
  version: 1.0.0
  title: Petstore API 
produces:
- application/json
paths:
  /pets:
    get:
      summary: List all pets 
      responses:
        200:
          description: OK
        500:
          description: Internal Server Error
    post:
      summary: Add a new pet 
      parameters:
        - in: body
          name: body
          schema:
            "$ref": "#/definitions/pet"
          required: true
      responses:
        201:
          description: Created
        500:
          description: Internal Server Error

definitions:
  pet:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      tag:
        type: string

4. Generate API server framework

Next , you need to use the go-swagger tool to generate code. The code generator will automatically generate code using the configuration defined in the previous step. Enter the following command in the terminal:

$ swagger generate server -A Go-Swagger-API -f pets.yaml

This command will generate the server-side framework based on the definition in the YAML file.

5. Start the API server

Next, you need to start the API server and verify that it is working properly. Enter the following command in the terminal:

$ cd cmd/go-swagger-api-server/
$ go run main.go

The output should look similar to the following:

Serving Go-Swagger-API at http://127.0.0.1:8080 

You should now be able to access the following URL in your web browser to verify that the API is working: http://127.0.0.1:8080/pets.

6. Integrate SwaggerUI

The last step is to integrate SwaggerUI in the API server. First, create a directory named swagger-ui in the root directory of the project and download SwaggerUI in it. This can be achieved by running the following command:

$ mkdir swagger-ui && cd swagger-ui && wget https://github.com/swagger-api/swagger-ui/archive/v3.32.3.tar.gz && tar xfz v3.32.3.tar.gz --strip-components=1 && rm v3.32.3.tar.gz

Next, in the main.go file of the API server Add the following code:

// Setup the SwaggerUI middleware
swaggerUI := http.FileServer(http.Dir("./swagger-ui/dist"))
r.PathPrefix("/docs").Handler(http.StripPrefix("/docs", swaggerUI))

This code exposes the dist directory in SwaggerUI as a static resource file for rendering the actual SwaggerUI.

Now, you can visit the following URL in your browser to view the automatically generated API documentation: http://localhost:8080/docs/index.html.

Conclusion

It is not difficult to use SwaggerUI to implement API online documentation in Golang, which brings great convenience to the writing and maintenance of API documentation. By using Swagger, documentation can be automatically generated for the API, and back-end engineers and front-end engineers can quickly understand the API interface. This greatly simplifies the API development, testing and documentation process, allowing developers to focus more on the implementation of business logic.

The above is the detailed content of Using SwaggerUI to implement API online documentation in Golang. For more information, please follow other related articles on the PHP Chinese website!