Use OpenAPI/Swagger to write API documents in Go language

In recent years, with the continuous development of Internet technology, the importance of Web API interfaces has become more and more important, and writing API documents has become an important part of development work. In Go language, we can use OpenAPI/Swagger to write API documents.

OpenAPI/Swagger is an API specification and tool chain that can help us build and describe API interfaces that conform to the RESTful architectural style. It contains a set of standardized API description languages ​​and a series of tools that can help us automatically generate API documents, client code and server framework.

In the Go language, you can use Swagger's Go official implementation "swag" to quickly generate API documents. Below we will learn how to use swag to write API documentation.

First, we need to add swag to the project. You can use the following command to add it to the project:

go get -u github.com/swaggo/swag/cmd/swag

After installing swag, we need to import swag related information in the main.go file Package:

import (
    "github.com/swaggo/files"
    "github.com/swaggo/gin-swagger"
    "github.com/gin-gonic/gin"
)

// 注册swag
func setUpSwagger(engine *gin.Engine) {
    engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}

func main() {
    // 初始化 gin 引擎
    engine := gin.Default()
    setUpSwagger(engine)
    router.LoadRouters(engine)
    _ = engine.Run()
}

Next, we can use swagger annotations to describe the interface in the interface annotation. For example:

// User register router
// @Summary User register router
// @Description User register router
// @Tags Users
// @Accept  json
// @Produce  json
// @Param user_in body models.NewUser true "user info"
// @Success 200 {string} json "{"code":200,"data":null,"msg":"Register successful"}"
// @Failure 400 {string} json "{"code":400,"msg":"Bad Request"}"
// @Router /users/register [post]
func Register(c *gin.Context) {
    name := c.PostForm("name")
    password := c.PostForm("password")
    ...
}

In the comments, we use some swagger annotations:

• @Summary: Interface summary information
• @Description: Interface detailed description
• @Tags: The tag to which the interface belongs
• @Accept: Interface request Content-Type
• @Produce: Interface response Content-Type
• @Param: Interface parameter description , including parameter position, parameter name, whether it is a required parameter, parameter description and parameter example
• @Success: Interface successful response description, which can include response Code, response information and response data structure
• @Failure: Interface failure response description, which can also include response code and response information

Finally, we need to use the swag init command in the project root directory to generate API documentation. The documentation will be generated in the docs directory.

swag init

Now, we can view the API documentation by visiting http://localhost:8080/swagger/index.html.

In general, using OpenAPI/Swagger to write API documents can help us describe the interface more clearly and make it easier to read and understand. The swag library of the Go language can quickly generate API documents, allowing us to develop more efficiently.

The above is the detailed content of Use OpenAPI/Swagger to write API documents in Go language. For more information, please follow other related articles on the PHP Chinese website!