go restful 生成 swagger 2.0 文档

43 阅读 0 评论 29 点赞

我是靠谱客的博主苹果大地，最近开发中收集的这篇文章主要介绍go restful 生成 swagger 2.0 文档，觉得挺不错的，现在分享给大家，希望可以做个参考。

概述

什么是swagger

Swagger 允许您描述 API 的结构，以便机器能够读取它们。Swagger 所有能力中最卓越的是 api 描述自身结构的能力。为什么他这么棒?通过阅读API的结构，我们可以自动构建漂亮的交互式 API 文档。我们还可以用多种语言为您的 API 自动生成服务端库，并探索其他可能性，比如自动化测试。Swagger 通过请求 API 返回包含整个 API 详细描述的 YAML 或 JSON 来实现这一点。这个文件本质上是您的API的资源列表，它遵循OpenAPI规范。该规范要求您包括以下信息:

您的API支持哪些操作?
您的API的参数是什么?它返回什么?
您的API需要一些授权吗?
甚至还有一些有趣的东西，比如术语、联系信息和使用API的许可。

您可以手动为您的 API 编写一个 Swagger 规范，或者让它从源代码中的注释自动生成。

一些与swagger 相关的工具：

swagger ui 生成交互式API文档，让用户直接在浏览器中尝试API调用。
swagger CodeGen 用API文档生成代码
swagger edit 集合了 swagger ui 和 swagger CodeGen 的部分功能

搭建swagger相关的工具

这里只需要搭建 swagger ui 和 swagger edit 就可以了，搭建swagger edit 是为了从网页端生成代码。搭建swagger ui 是为了可以读取API文档，生成交互式API。
以下是使用docker搭建的方式：

搭建 swagger edit

docker run -d -p 8081:8080 swaggerapi/swagger-editor

访问 http://IP:8081即可看到 swagger editor页面了。swagger editor 既可以编写 swagger 2.0 也可编写 swagger 3.0 。但是，swagger 3.0 可生成代码的种类明显少于2.0，这也是我为什么用2.0 的原因。

搭建 swagger ui

docker run -d -p 8082:8080 swaggerapi/swagger-ui

swagger 2.0 API 文档的结构

swagger 2.0的文档结构可以参考https://swagger.io/docs/specification/2-0/basic-structure/,如果你不愿意读英文的，我简单翻译了一下下https://github.com/SongJXin/swagger-2.0-translate/blob/master/基本结构.md。
下面这个 API 文档是由之后的 go-restful 生成的。

swagger: '2.0'
info:
description: Resource for managing Users
title: UserService
contact:
name: john
url: 'http://johndoe.org'
email: john@doe.rp
license:
name: MIT
url: 'http://mit.org'
version: 1.0.0
paths:
/users:
get:
consumes:
- application/xml
- application/json
produces:
- application/json
- application/xml
tags:
- usersa
summary: get all users
operationId: findAllUsers
responses:
'200':
description: OK
schema:
type: array
items:
$ref: '#/definitions/main.User'
put:
consumes:
- application/xml
- application/json
produces:
- application/json
- application/xml
tags:
- usersa
summary: create a user
operationId: createUser
parameters:
- name: body
in: body
required: true
schema:
$ref: '#/definitions/main.User'
responses:
'200':
description: OK
'/users/{user-id}':
get:
consumes:
- application/xml
- application/json
produces:
- application/json
- application/xml
tags:
- usersa
summary: get a user
operationId: findUser
parameters:
- type: integer
default: 1
description: identifier of the user
name: user-id
in: path
required: true
responses:
'200':
description: OK
schema:
$ref: '#/definitions/main.User'
'404':
description: Not Found
put:
consumes:
- application/xml
- application/json
produces:
- application/json
- application/xml
tags:
- usersa
summary: update a user
operationId: updateUser
parameters:
- type: string
description: identifier of the user
name: user-id
in: path
required: true
- name: body
in: body
required: true
schema:
$ref: '#/definitions/main.User'
responses:
'200':
description: OK
delete:
consumes:
- application/xml
- application/json
produces:
- application/json
- application/xml
tags:
- usersa
summary: delete a user
operationId: removeUser
parameters:
- type: string
description: identifier of the user
name: user-id
in: path
required: true
responses:
'200':
description: OK
definitions:
main.User:
required:
- id
- name
- age
properties:
age:
description: age of the user
type: integer
format: int32
default: 21
id:
description: identifier of the user
type: string
name:
description: name of the user
type: string
default: john
tags:
- description: Managing users
name: users

go restful 集成 swagger 2.0

获取 go restful 和 swagger 相关的包

go get github.com/emicklei/go-restful
go get github.com/emicklei/go-restful-openapi

代码先贴为敬（这个代码是go-restful-openapi中自带的例子）：

package main
import (
"log"
"net/http"
"github.com/emicklei/go-restful"
restfulspec "github.com/emicklei/go-restful-openapi"
"github.com/go-openapi/spec"
)
type UserResource struct {
// normally one would use DAO (data access object)
users map[string]User
}
func (u UserResource) WebService() *restful.WebService {
ws := new(restful.WebService)
ws.
Path("/users").
Consumes(restful.MIME_XML, restful.MIME_JSON).
Produces(restful.MIME_JSON, restful.MIME_XML) // you can specify this per route as well
tags := []string{"users"}
ws.Route(ws.GET("/").To(u.findAllUsers).
// docs
Doc("get all users").
Metadata(restfulspec.KeyOpenAPITags, tags).
Writes([]User{}).
Returns(200, "OK", []User{}))
ws.Route(ws.GET("/{user-id}").To(u.findUser).
// docs
Doc("get a user").
Param(ws.PathParameter("user-id", "identifier of the user").DataType("integer").DefaultValue("1")).
Metadata(restfulspec.KeyOpenAPITags, tags).
Writes(User{}). // on the response
Returns(200, "OK", User{}).
Returns(404, "Not Found", nil))
ws.Route(ws.PUT("/{user-id}").To(u.updateUser).
// docs
Doc("update a user").
Param(ws.PathParameter("user-id", "identifier of the user").DataType("string")).
Metadata(restfulspec.KeyOpenAPITags, tags).
Reads(User{})) // from the request
ws.Route(ws.PUT("").To(u.createUser).
// docs
Doc("create a user").
Metadata(restfulspec.KeyOpenAPITags, tags).
Reads(User{})) // from the request
ws.Route(ws.DELETE("/{user-id}").To(u.removeUser).
// docs
Doc("delete a user").
Metadata(restfulspec.KeyOpenAPITags, tags).
Param(ws.PathParameter("user-id", "identifier of the user").DataType("string")))
return ws
}
// GET http://localhost:8080/users
//
func (u UserResource) findAllUsers(request *restful.Request, response *restful.Response) {
list := []User{}
for _, each := range u.users {
list = append(list, each)
}
response.WriteEntity(list)
}
// GET http://localhost:8080/users/1
//
func (u UserResource) findUser(request *restful.Request, response *restful.Response) {
id := request.PathParameter("user-id")
usr := u.users[id]
if len(usr.ID) == 0 {
response.WriteErrorString(http.StatusNotFound, "User could not be found.")
} else {
response.WriteEntity(usr)
}
}
// PUT http://localhost:8080/users/1
// <User><Id>1</Id><Name>Melissa Raspberry</Name></User>
//
func (u *UserResource) updateUser(request *restful.Request, response *restful.Response) {
usr := new(User)
err := request.ReadEntity(&usr)
if err == nil {
u.users[usr.ID] = *usr
response.WriteEntity(usr)
} else {
response.WriteError(http.StatusInternalServerError, err)
}
}
// PUT http://localhost:8080/users/1
// <User><Id>1</Id><Name>Melissa</Name></User>
//
func (u *UserResource) createUser(request *restful.Request, response *restful.Response) {
usr := User{ID: request.PathParameter("user-id")}
err := request.ReadEntity(&usr)
if err == nil {
u.users[usr.ID] = usr
response.WriteHeaderAndEntity(http.StatusCreated, usr)
} else {
response.WriteError(http.StatusInternalServerError, err)
}
}
// DELETE http://localhost:8080/users/1
//
func (u *UserResource) removeUser(request *restful.Request, response *restful.Response) {
id := request.PathParameter("user-id")
delete(u.users, id)
}
func main() {
u := UserResource{map[string]User{}}
restful.DefaultContainer.Add(u.WebService())
config := restfulspec.Config{
WebServices: restful.RegisteredWebServices(), // you control what services are visible
APIPath:
"/apidocs.json",
PostBuildSwaggerObjectHandler: enrichSwaggerObject}
restful.DefaultContainer.Add(restfulspec.NewOpenAPIService(config))
// Optionally, you can install the Swagger Service which provides a nice Web UI on your REST API
// You need to download the Swagger HTML5 assets and change the FilePath location in the config below.
// Open http://localhost:8080/apidocs/?url=http://localhost:8080/apidocs.json
//http.Handle("/apidocs/", http.StripPrefix("/apidocs/", http.FileServer(http.Dir("/Users/emicklei/Projects/swagger-ui/dist"))))
// Optionally, you may need to enable CORS for the UI to work.
cors := restful.CrossOriginResourceSharing{
AllowedHeaders: []string{"Content-Type", "Accept"},
AllowedMethods: []string{"GET", "POST", "PUT", "DELETE"},
CookiesAllowed: false,
Container:
restful.DefaultContainer}
restful.DefaultContainer.Filter(cors.Filter)
log.Printf("Get the API using http://localhost:8080/apidocs.json")
log.Printf("Open Swagger UI using http://10.110.27.102:8082/?url=http://localhost:8080/apidocs.json")
log.Fatal(http.ListenAndServe(":8080", nil))
}
func enrichSwaggerObject(swo *spec.Swagger) {
swo.Info = &spec.Info{
InfoProps: spec.InfoProps{
Title:
"UserService",
Description: "Resource for managing Users",
Contact: &spec.ContactInfo{
Name:
"john",
Email: "john@doe.rp",
URL:
"http://johndoe.org",
},
License: &spec.License{
Name: "MIT",
URL:
"http://mit.org",
},
Version: "1.0.0",
},
}
swo.Tags = []spec.Tag{spec.Tag{TagProps: spec.TagProps{
Name:
"users",
Description: "Managing users"}}}
}
// User is just a sample type
type User struct {
ID
string `json:"id" description:"identifier of the user"`
Name string `json:"name" description:"name of the user" default:"john"`
Age
int
`json:"age" description:"age of the user" default:"21"`
}

api 文档生成规则

package main和 import部分就略过了。
UserResource这个类是go-restful的基本结构关于go-restful框架的这里就不多说了。

enrichSwaggerObject这个函数，是对应生成了swagger 2.0 API 文档（下称API文档）的info和 tags部分。

User 这个结构，即被go-restful使用，作为操作的对象，也是对应了API文档的definitions部分。在反单引号（`）之间的内容规定了这个结构体与definitions的对应关系。

WebService函数中：
ws.path().Consumes().Produces()对应swagger 2.0 中的basePath和Consumes、Produces，只不过，在生成API过程中把他们分解到了具体的每一个path。
tags就是个字符串数组，在ws.Route.Metadata中用到，规定了这个path的标签，如果enrichSwaggerObject中定义的tags定义了这个tag,将从里面取对应的Description信息，如果没有定义，就当作一个全新的tag。
ws.Route生成了API文档的path
ws.Route(ws.GET)对应了一个path的一个operation
ws.Route.To这里是go-restful框架将请求路由到相应的函数（用词可能不准确，大概就是这么个意思，这函数处理这次请求），同时，在生成API文档的时候，函数的名称会做为path.operation.operationId。
ws.Route.Doc对应生成了API文档的 path.operation.summary
ws.Route.Writes生成的path.operation.responses.default（这里有个很奇怪的现象。我用 chrome 和 firefox 看到的生成的API是不一样的，chrome 不会显示这个path.operation.responses.default字段，在swagger ui中可以看到这个字段）
ws.Route.Return这里生成path.operation.responses对应的状态码的返回。第一个参数，对应状态码，第二个参数对应description，第三个参数对应了schema
ws.Route.Param生成API文档的parameter
ws.Route.Reads也是生成API文档的parameter，区别是它使用了schema，引用了definitions中的对象

main函数中：
config设置了生成API文档的一些配置:

WebServices,为哪个WebServices 生成 API文档
APIPath,访问API文档的路径。
PostBuildSwaggerObjectHandler,使用的基本信息（info和tags）

http.Handle是这个程序和swagger ui在同一个服务器上，启动这个程序的时候同时启动swagger ui用的，这里用了外部的，就把它注释掉了，不用它了。
cors 这个过滤器是为了让swagger ui能够访问到这个 API文档，没有的话，用swagger ui访问会报错。

swagger UI 访问API文档。

访问http://swaggerUI-ip:8082/?url=http://localhost:8080/apidocs.json就可以看到 swagger ui 解析API 文档后的交互式API文档了。

最后

以上就是苹果大地为你收集整理的go restful 生成 swagger 2.0 文档的全部内容，希望文章能够帮你解决go restful 生成 swagger 2.0 文档所遇到的程序开发问题。

如果觉得靠谱客网站的内容还不错，欢迎将靠谱客网站推荐给程序员好友。

本图文内容来源于网友提供，作为学习参考使用，或来自网络收集整理，版权属于原作者所有。

本文分类：开发
浏览次数：43 次浏览
发布日期：2023-12-18 15:00:21
本文链接：https://www.kaopuke.com/article/k-p-k_13_u_23_o_2_fz_13_jg3.html

go restful 生成 swagger 2.0 文档

概述

什么是swagger

搭建swagger相关的工具

搭建 swagger edit

搭建 swagger ui

swagger 2.0 API 文档的结构

go restful 集成 swagger 2.0

api 文档生成规则

swagger UI 访问API文档。

最后

评论列表共有 0 条评论

发表评论取消回复

go restful 生成 swagger 2.0 文档

概述

什么是swagger

搭建swagger相关的工具

搭建 swagger edit

搭建 swagger ui

swagger 2.0 API 文档的结构

go restful 集成 swagger 2.0

api 文档生成规则

swagger UI 访问API文档。

最后

相关文章

评论列表共有 0 条评论

发表评论 取消回复

发表评论取消回复