How to install swag to generate golang API documentation

Swag is a tool for quickly building Go applications that automatically generates Swagger documentation. Developers can automatically generate API documentation by simply adding some comments to their code. Swag supports generating API documents according to RESTful API standards, and also supports generating Markdown and HTML formats.

In this article, we will introduce how to install and use Swag in golang.

Step 1 - Install Swag

Swag can be installed from GitHub using the go get command. Use the following command to install Swag:

$ go get github.com/swaggo/swag/cmd/swag

After the installation is complete, you can install it in $GOPATH/ Find the "swag" binary file in the bin path. Now, we can continue to use Swag to generate API documentation.

Step 2 - Generate API documentation

Swag requires some special code comments to correctly generate API documentation. Here are some sample comments:

// @Summary 创建用户
// @Description 创建一个新用户
// @Tags 用户管理
// @Accept json
// @Produce json
// @Param user body User true "用户信息"
// @Success 200 {string} string "成功"
// @Failure 400 {string} string "请求错误"
// @Failure 500 {string} string "服务器内部错误"
// @Router /users [post]
func CreateUser(c *gin.Context) {
    // ...
}

The comments above describe an API on how to create a user. Swag searches for these special comments in the code and then builds the documentation.

Execute the following command to generate documentation:

$ swag init

This will scan your application and generate Swagger JSON files and Swagger UI.

Step 3 - Add Swagger's UI

Swagger UI provides an interactive interface for viewing and testing the API. We can add Swagger UI to our web application.

// main.go
package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
    "github.com/swaggo/files" // swagger embed files
    "github.com/swaggo/gin-swagger" // gin-swagger middleware
    _ "github.com/user/repo/docs" // docs is generated by Swag CLI, you have to import it.
)

func main() {
    r := gin.New()

    // use ginSwagger middleware to serve the API docs
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    //...
}

Assume you have generated the document using Swag. Now you can view the API documentation by opening the following link in your browser:

http://localhost:8080/swagger/index.html

This is Swagger's Web UI that you can use to view and test the API.

Summary

In this article, we introduced how to install and use Swag in Golang. With Swagger's annotations and commands, you can easily generate API documentation. Swag makes the whole process quick and easy, and documentation using Swag integrates well with the Swagger UI

The above is the detailed content of How to install swag to generate golang API documentation. For more information, please follow other related articles on the PHP Chinese website!