Introduction to swagger (GO) API Documentation tools

• swaggo
• swagger

Install the swag command

go get -u github.com/swaggo/swag/cmd/swag
Copy the code

Write a comment

• Basic Service Information

// @title Swagger Usage example
/ / @ version 1.0
// @description Swagger
func main(a){
	r := gin.Default()
    r.GET("/check", connectCheck)
    ...
}
Copy the code

• API information

type Response struct{
	Code uint32 `json:"code"`
	Message uint32 `json:"message"`
	Data interface{} `json:"data"`
}

type ResponseError struct{
	Code uint32 `json:"code"`
	Message uint32 `json:"message"`
}

// @summary service connection verification --> Interface introduction
// @description service initial connection test --> interface Description
// @accept json --> Receive type
// @produce json --> return type
// Success 200 {object} Response --> Return data structure on Success
// Failure 400 {object} ResponseError --> Return data structure after Failure
// Failure 404 {object} ResponseError
// Failure 500 {object} ResponseError
// @router /check [get] --> Router address and request method
func connectCheck(c *gin.Context){
	res := Response{ Code: 1001, Message: "OK", Data: "connect success !!!"}
	c.JSON(http.StatusOK, res)
}

Copy the code

Generating documentation

// The root directory executes swag initCopy the code

Configuring Document Routing

import ( ... GinSwagger "github.com/swaggo/gin-swagger" swaggerFiles "github.com/swaggo/files") func main(){ ... r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) r.Run(":8080") }Copy the code

Start the service and access

Go run main. Go / / the current document path: localhost: swagger/index. The HTMLCopy the code

API annotation definition

• The summary introduction

  / / @ the Summary introduction
  Copy the code

• Accept Specifies the MIME type to use

  // @Accept json
  Copy the code

• Produce Specifies the MIME type that can be generated in response to the return type

  // @Produce json
  // @produce PNG Multiple files can be configured
  Copy the code

• Param Parameter format: [Parameter Name Parameter Type Data Type Mandatory Remarks Restricted Attribute] Space split

  @Params userId query string true "User id" minlength(3) maxlength(100)
  @Params status query integer false "Status: 0 1" Enums(0.1) defualt(0) 
  Copy the code

  • Parameter available type [param type]
    • query
    • path
    • header
    • body
    • formDate
  • Data available type [data type]
    • string(string)
    • integer(int, uint, uint32, uint64)
    • boolean(bool)
    • user defined struct
  • Configurable property
    • Defualt * Parameter default value
    • Maximum number
    • Mininum number Minimum value
    • MaxLength Integer Indicates the maximum length
    • MinLength Integer Specifies the minimum length
    • Enums [*] Enumeration type
    • format string
    • CollectionFormat String Query Array division mode

• Security safety

• Success Response format: [Status code {Data type} Data Type Remarks]

  @Success 200 {object} Response "Return empty object"
  Copy the code

• Failure Response format: [Status code {data type} Data type Remarks]

  @Failure 400 {object} ResponseError
  Copy the code

• Header Format of the request header field: [Status code {Data type} Data type Remarks]

  // @Header 200 {string} Token "qwerty"
  Copy the code

• Router Routing path

  // @Router /user/{userId} [get]
  Copy the code

• X-name Indicates the extended field

  type Account struct {
      ID   string    `json:"id" extensions:"x-nullable,x-abc=def"` // The extended field must begin with "x-"
  }
  Copy the code

Structure description

• Example example

type User struct{
	ID int `json:"id" example:"232323"`
	Name string `json:"name" example:"Coco" `
}
Copy the code

• Limit properties

  type User struct{
  	ID int `json:"id" minLength:"3" maxLength:"100"`
  }
  Copy the code

• Swaggerignore excludes fields

  type Account struct {
      ID   string    `json:"id"`
      Name string     `json:"name"`
      Ignored int     `swaggerignore:"true"` // Exclude the Ignored field
  }
  Copy the code

• rename

  type Resp struct {
      Code int
  }//@name Response must be placed at the end of the structure
  Copy the code

Matters needing attention

• Multi-field definitions cannot be cross-field

  // @Accept json
  // @Produce json
  // @param id query string false "user ID" default("") minlength(3) maxlength(100)
  // @produce json will Produce an error
  Copy the code

• After modifying the definition, you need to run the command again to generate the command and restart the service

• Import documents when configuring routes