GoSwagger

Swagger

一个一键生成API文档的工具。GoSwagger，Golang版本的Swagger，支持在代码中编写注释，通过Swagger编译后生成API文档。

Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。

——《使用go-swagger为golang API自动生成swagger文档》

安装方式

通过brew安装

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

其余的安装方式请移步：Install goswagger

动手实践

《使用go-swagger为golang API自动生成swagger文档》已经给出了部分用法。以下为对用法的基本实践。

建立实践项目

go mod init github.com/xxx/swagger_lesson
touch doc.go
touch api.go
mkdir models
cd models
touch user.go
touch resp.go

doc.go中的内容：

// 这是一份用于实验GoSwagger的学习代码
//
//	Schemes: http, https
//	Host: localhost
//	BasePath: v1
//	Version: 0.0.1
//	License: MIT http://opensource.org/licenses/MIT
//	Contact: alpha qiu<[email protected]> https://alphaqiu.github.io
//
// swagger:meta
package main

import "github.com/alphaqiu/swagger_lesson/models"

// swagger:parameters UpdateUserResponseWrapper
type UpdateUserRequest struct {
	// in: body
	Body models.User
}

// Update User Info
//
// swagger:response UpdateUserResponseWrapper
type UpdateUserResponseWrapper struct {
	// in: body
	Body models.ResponseMessage
}

// swagger:route POST /users users UpdateUserResponseWrapper
//
// Update User
//
// This will update user info
//
//     Responses:
//       200: UpdateUserResponseWrapper

首先在package上的注释定义swagger:meta信息。然后声明输入和输出。UpdateUserRequest 为输入，swagger注释成swagger:parameters，后跟一个或多个输出的引用（语法：swagger:parameters [operationid1 operationid2]，这里的输出引用指向UpdateUserResponseWrapper）。

其次定义输入参数。Body这个输入参数类型定义为in: body，表示以POST方式传输数据。也可限定required: true表示必填参数。

定义输出。UpdateUserResponseWrapper为输出参数。swagger注释成swagger:response，后跟一个可选输出的引用（语法：swagger:response [?response name]）。

定义输出参数。Body这个输入参数类型定义为in: body，表示以POST方式传输数据。也可限定required: true表示必填参数。

定义路由。

// swagger:route POST /users users UpdateUserResponseWrapper
//
// Update User
//
// This will update user info
//
//     Responses:
//       200: UpdateUserResponseWrapper

以上注释代表了路由。swagger:route语法swagger:route [method] [path pattern] [?tag1 tag2 tag3] [operation id]，其中method表示GET或POST，path pattern表示为访问路径，tag表示成API的分组。operation id必填，用于客户端生成方法名。

api.go中的内容：

package main

import "net/http"

func UpdateUser(w http.ResponseWriter, req *http.Request) {

}

api.go表现为与接口定义无关。因为在doc.go中已定义。

models/user.go中内容：

package models

// User represents the user for this application
//
// A user is the security principal for this application.
// It's also used as one of main axes for reporting.
//
// A user can have friends with whom they can share what they like.
//
// swagger:model
type User struct {
	// The name for this user
	//
	// required: true
	// example: Jane
	Name string `json:"name"`
	// the age for this user
	//
	// required: false
	// min: 18
	// example: 18
	Age int `json:"age"`
}

声明模型相关的说明和约束。

models/resp.go中的内容：

package models

type ResponseMessage struct {
		Code int `json:"code"`
		Name string `json:"name"`
}

resp.go中未声明，走默认值。

生成配置

swagger generate -o ./swagger.json

查看接口

swagger serve ./swagger.json