api文档管理方案思考

需求

1.代码即文档，代码与文档一致

2.文档易维护，有版本可回溯

调研

1.市面上流通性较好的规范有 openapi

其定义基本满足一个api的所有描述要求

2. 基于openapi的规范的主流工具

名称	开源	mock	文档	注释	版本	协作
postman	是	否	openapi	否	否	否
apipost	否	是	openapi md	是	是	是
apifox	否	是	openapi md	是	是	是
yapi	是	是	openapi md	是	是(弱)	是(弱)
swagger	是	否	openapi	是	否	否
Knife4j	是	否	openapi md	是	是(弱)	是(弱)

方案

1. swagger + yapi+ git

  git触发cicd控制swagger生产openapi，yapi定期同步openapi，md人工选择导出
  优点：
	 1. 代码与openapi一致
	 2. 文档与代码按需同步，yapi支持低成本的所有功能
  缺点：
	 1. md靠yapi管理 

2. swagger(Knife4j) + git

  git触发cicd控制swagger生产openapi 和 md,md可以通过Knife4j来美化
  优点：
	 1. 代码与openapi一致
	 2.  文档与代码按需同步, Knife4j支持低成本的所有功能
  缺点：
	 1. md靠Knife4j管理，不支持mock

3. swagger生成工具

a. swag 6.9k

 原理：通过扫描构建ast树后，解析制定注释中的自定义token 或者 tag中得标签进行openapi文档生成。
特点:
1.注解风格注释
2.支持example
3.支持tag

eg

注解

paackge main
import (
    "github.com/gin-gonic/gin"
    ginSwagger "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
    _ "my/docs"
)
// @title 这里写标题
// @version 1.0
// @description 这里写描述信息
// @termsOfService [http://swagger.io/terms/](http://swagger.io/terms/)
// @contact.name 这里写联系人信息`
// @contact.url [http://www.swagger.io/support](http://www.swagger.io/support)
// @contact.email [email protected]
// @host 这里写接口服务的host
// @BasePath 这里写base path
func main() {
    r := gin.Default()
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    r.GET("/testapi", TestApi)
    r.Run(":8067")

}

api

// InPut example
type InPut struct {
    //int参数
    ParamInt int `json:"param_int"  example:"1" default:"1" binding:"required"`
    // 字符串参数
    ParamString string `json:"param_string" example:"param_string" default:"param_string" binding:"required"`
    // 布尔参数
    ParamBool bool `json:"param_bool" example:"true" default:"true" binding:"required"`
    // 浮点参数
    ParamFloat64 float64 `json:"param_float_64" format:"int64" example:"1" default:"1" binding:"required"`
    // 键值参数
    ParamMap map[string]string `json:"param_map" swaggertype:"string,string" example:"en:Map,ru:Карта,kk:Карталар"`
    // 数组参数
    ParamSlice []string `json:"param_slice"  example:"1,2" enums:"1,2,3,5,7"`
    // interface类型参数
    ParamInterface interface{} `json:"param_interface" swaggertype:"string" example:"param_interface" default:"param_interface"`
    // 结构类型参数
    ParamStruct Param `json:"param_struct"`
    // 时间参数
    ParamDateTime time.Time `json:"param_date_time"`
}


// Param example
type Param struct {
    //名字参数
    Name string `json:"name" example:"assss" default:"sdas"`

}


// OutPut example
type OutPut struct {
    //错误码
    Code int `json:"code"`
    //消息
    Msg string `json:"msg""`
    //数据
    Data interface{} `json:"data"`
}


// TestApi
// @Summary api大标题
// @Description api描述
// @Tags    标签,文档以标签聚合，建议只用domain或者包
// @Accept  json
// @Produce  json
// @param Authorization header string true "验证参数Bearer和token空格拼接"
// @Param  body body InPut true "交款查询参数"
// @Success 200 {object} OutPut
// @Failure 500 {object} OutPut
// @Router /app/pay/list [post]
func TestApi(c *gin.Context) {
    // write your code
}

b. go-swagger 8k

原理：注释必须符合doc规范。通过扫描构建ast树后，解析制定注释中的自定义token进行openapi文档生成。
特点:  
1.支持原汁原味的swagger注释功能
2.支持markdown文档导出
3.支持反向生成客户端、服务端
4.符合godoc规范

eg

注解

// Package example Example API.
//
// the purpose of this application is to provide an application
// that is using plain go code to define an API
//
// This should demonstrate all the possible comment annotations
// that are available to turn go code into a fully compliant swagger 2.0 spec
//
// Terms Of Service:
//
// there are no TOS at this moment, use at your own risk we take no responsibility
//
//     Schemes: http, https
//     Host: localhost
//     BasePath: /v2
//     Version: 0.0.1
//     License: MIT http://opensource.org/licenses/MIT
//     Contact: John Doe http://john.doe.com
//
//     Consumes:
//     - application/json
//
//     Produces:
//     - application/json
//
// swagger:meta
package example
// APIVersion shows this API's current version
var APIVersion string

api

import (
    "net/http"
    "time"
    "github.com/go-openapi/runtime/middleware/denco"
    "goswg-demo/swagger-go/enums"
)

// A PetQueryFlags contains the query flags for things that list pets.
// swagger:parameters listPets
type PetQueryFlags struct {
    // Status
    Status enums.Status `json:"status"`

    // Birthday
    //
    // swagger:strfmt date
    Birthday time.Time `json:"birthday"`

}

// GetPets swagger:route GET /pets pets listPets
//
// Lists the pets known to the store.
//
// By default it will only lists pets that are available for sale.
// This can be changed with the status flag.
//
// Deprecated: true
// Responses:
//      default: genericError
//          200: []pet
func GetPets(w http.ResponseWriter, r *http.Request, params denco.Params) {
    // some actual stuff should happen in here

}

// A Pet is the main product in the store.
// It is used to describe the animals available in the store.
//
// swagger:model pet
type Pet struct {
    // The id of the pet.
    //
    // required: true
    ID int64 `json:"id"`

    // The name of the pet.
    //
    // required: true
    // pattern: \w[\w-]+
    // minimum length: 3
    // maximum length: 50
    Name string `json:"name"`

    // The photo urls for the pet.
    // This only accepts jpeg or png images.
    //
    // items pattern: \.(jpe?g|png)$
    PhotoURLs []string `json:"photoUrls,omitempty"`
    
    // The current status of the pet in the store.
    Status enums.Status `json:"status,omitempty"`

    // Extra bits of information attached to this pet.
    //
    Tags []Tag `json:"tags,omitempty"`

    // The pet's birthday
    //
    // swagger:strfmt date
    Birthday time.Time `json:"birthday"`
}

相关阅读

Knife4j部署