0717-7821348
500万彩票网怎么样了

500万彩票网怎么样了

您现在的位置: 首页 > 500万彩票网怎么样了
运用 SwaggerUI 创立 Golang API 文档
2019-09-06 22:05:59

为你的 API 供给一个文档比你幻想中愈加有用,即便你没有揭露你的 API ,为你的前端或许移动团队供给一个文档会比你供给截图/片段或运用 Postman/Insomnia (带有同步的高档版别)等付费产品更简略。凭借 SwaggerUI ,您能够主动取得一切 API 的规划杰出的文档。当切换到 Go 时,因为短少文档/教程,我在装备它的时分呈现了一些问题,所以我决议写一个。

示例程序:链接 https://github.com/ribice/golang-swaggerui-example

大约两年前,我曾经在开发一个 RESTful 风格的企业运用的后台时,第一次知道 SwaggerUI 。 SwaggerUI 的创造者 SmartBear 将其产品描绘为:

"Swagger UI 答应任何人(无论是你的开发团队仍是最终用户)在没有任何完成逻辑的状况下对 API 资源进行可视化和交互。它(API文档)经过 Swagger 界说主动生成,可视化文档使得后端完成和客户端消费变得愈加简略。"

简而言之,经过供给 Swagger(OpenAPI)界说,您能够取得与 API 进行交互的界面,而不用关怀编程言语自身。你能够将 Swagger(OpenAPI) 视为 REST 的 WSDL 。

作为参阅,Swagger Codegen 能够从这个界说中,用几十种编程言语来生成客户端和服务器代码。

回到那个时分,我运用的是 Java 和 SpringBoot ,觉得 Swagger 简略易用。你仅需创立一次 bean ,并增加一两个注解到端点上,再增加一个标题和一个项目描绘。此外,我习气将一切恳求从 “/” 重定向到 “/swagger-ui” 以便在我翻开 host:port 时主动跳转到 SwaggerUI 。在运转运用程序的时分, SwaggerUI 在同一个端口依然可用。(例如,您的运用程序运转在[host]:[port], SwaggerUI 将在[host]:[port]/swagger-ui上访问到)。

快一年半之后,我想在咱们的 Go 项目中完成 SwaggerUI 。问题是 —— 感觉太杂乱了。当我在网络上查找时,我看到不仅仅是我,其他许多用户也遇到了相同的费事。

我偶尔发现了 Go-Swagger 项目。他们的 GitHub Readme 议论的是 Swagger ,而不是 SwaggerUI 。你得有一个客户端,服务器,中间件和一些其他的东西,才能够考虑 SwaggerUI 。简而言之, Swagger 服务器/客户端用于从 Swagger 界说(swagger.json)中生成(后端)代码。生成服务器使您能够从标准中供给 API ,一起为这些 API 运用者生成客户端。把它看作代码生成东西。我觉得这很有用,但那不是我想要的。

在社区的协助下(向 casualjim 致意)和一些查询,我成功地为咱们的项目生成了没有太多的样板代码的 API 文档。

别的,我预备了一个完成了 go-swagger 注释来生成有用的 swagger 文档示例,能够在这儿找到。

装置 Go-Swagger

在开端之前,您需求在本地机器上装置 go swagger 。这不是一个强制性的过程,但会使得更简略的运用 swagger 作业。装置它能够让你在本地测验你的注释,不然,你只能依托你的 CI 东西。

最简略的装置办法是经过运转 Homebrew / Linuxbrew :

brew tap go-swagger/go-swagger

brew install go-swagger

此外,你能够从这儿得到最新的二进制文件。

Swagger:meta [docs]

这是你应该增加到项目中的第一个注释。它被用来描绘你的项目称号,描绘,联络电子邮件,网站,许可证等等。

假如你的 API 仅供给在 HTTP 或 HTTPS 上,且只生成 JSON ,您应在此处增加它 - 答应你从每个路由中删去该注释。

安全也被增加在 swagger:meta 中,在 SwaggerUI 上增加一个授权按钮。为了完成JWT,我运用安全类型承载进行命名并将其界说为:

Swagger:route [docs]

有两种办法两个注释你的路由,swagger:operation 和swagger:route 。两者看起来都很类似,那么首要差异是什么?

把 swagger:route 看作简略 API 的短注释,它适用于没有输入参数(途径/查询参数)的 API 。那些(带有参数)的比方是 /repos/{owner} , /user/{id} 或许 /users/search?name=ribice

假如你有一个那种类型,那么你就有必要运用 swagger:operation ,除此之外,如 /user 或 /version 之类的 APIs 都能够用 swagger:route 来注释。

swagger:route注释包括以下内容:

  1. swagger:route - 注解
  2. POST - HTTP办法
  3. /repo - 匹配途径,端点
  4. repos - 路由地点的空间切割标签,例如,“repos users”
  5. createRepoReq - 用于此端点的恳求(具体的稍后会解说)
  6. Creates a new repository … - 摘要(标题)。关于swager:route注释,在第一个句号(.)前面的是标题。假如没有句号,就会没有标题而且这些文字会被用于描绘。
  7. If repository name exists … - 描绘。关于swager:route类型注释,在第一个句号(.)后边的是描绘。
  8. responses: - 这个端点的呼应
  9. 200: repoResp - 一个(成功的)呼应HTTP状况 200,包括 repoResp(用 swagger:response 注释的模型)
  10. 400: badReq, 409: conflict, 500: internal - 此端点的过错呼应(过错恳求,抵触和内部过错, 界说在 cmd/api/swagger/model.go 下)

如此注释您的端点将发生以下内容:

请记住,您还或许需求运用其他注释,具体取决于您的 API 。因为我将我的项运用 SwaggerUI 创立 Golang API 文档目界说为仅运用单一形式( https ),而且我的一切 API 都运用 https ,所以我不需求独自注释计划。假如您为端点运用多个形式,则需求以下注释:

// Schemes: http, https, ws, wss

相同适用于 顾客/生产者 媒体类型。我一切的 API 都只消费/生成 application/json 。假如您的 API 正在 消费/生成 其他类型,则需求运用该媒体类型对其进行注释。例如:

// consumes:
// - application/json
// - application/x-protobuf
//
// produces:
// - application/json
// - application/x-protobuf

安全性:

// security:
// api_key:
// oauth: read, write
// basicAuth:
// type: basic
// token:
// type: apiKey
// name: token
// in: query
// accessToken:
// type: apiKey
// name: access_token
// in: query

另一方面,swagger:operation 用于更杂乱的端点。三个破折号(-)下的部分被解析为 YAML ,答应更杂乱的注释。保证您的缩进是共同的和正确的,不然将无法正确解析。

Swagger:operation docs

运用 Swagger:operation 能够让你运用一切OpenAPI标准,你能够描绘你的杂乱的端点。假如你对细节感兴趣,你能够阅览标准文档。

简略来说 - swagger:operation 包括如下内容:

// swagger:operation GET /repo/{author} repos repoList
// ---
// summary: List the repositories owned by the given author.
// description: If author length is between 6 and 8, Error Not Found (404) will be returned.
// parameters:
// - name: author
// in: path
// description: username of author
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/reposResp"
// "404":
// "$ref": "#/responses/notFound"
  1. swagger:operation - 注释
  2. GET - HTTP 办法
  3. /repo/{author} - 匹配途径,端点
  4. repos - 路由地点的空间切割标签,例如,“repos users”
  5. repoList - 用于此端点的恳求。这个不存在(没有界说),但参数是强制性的,所以你能够用任何东西来替换repoList(noReq,emptyReq等)
  6. --- - 这个部分下面是YAML格局的swagger标准。保证您的缩进是共同的和正确的,不然将无法正确解析。留意,假如你在YAML中界说了标签,摘要,描绘或操作标签,将掩盖上述惯例swagger语法中的摘要,描绘,符号或操作标签。
  7. summary: - 标题
  8. description: - 描绘
  9. parameters: - URL参数(在这个比方中是{author})。字符串格局,强制性的(Swagger不会让你调用端点而不输入),坐落途径(/{author})中。另一种挑选是参数内嵌的恳求 (?name="")

界说你的路由后,你需求界说你的恳求和呼应。从示例中,你能够看到,我创立了一个新的包,命名为 swagger 。这不是强制性的,它把一切样板代码放在一个名为 swagger 的包中。但缺陷是你有必要导出你的一切 HTTP 恳求和呼应。

假如你创立了一个独自的 Swagger 包,保证将它导入到你的主/服务器文件中(你能够经过在导入前加一个下划线来完成):

_ "github.com/ribice/golang-swaggerui-example/cmd/swagger"

Swagger:parameters [docs]

依据您的运用程序模型,您的 HTTP 恳求或许会有所不同(简略,杂乱,封装等)。要生成 Swagger 标准,您需求为每个不同的恳求创立一个结构,乃至包括仅包括数字(例如id)或字符串(称号)的简略恳求。

一旦你有这样的结构(例如一个包括一个字符串和一个布尔值的结构),在你的Swagger包中界说如下:

// Request containing string
// swagger:parameters createRepoReq
type swaggerCreateRepoReq struct {
// in:body
api.CreateRepoReq
}
  • 第 1 行包括一个在 SwaggerUI 上可见的注释
  • 第 2 行包括 swagger:parameters 注释,以及恳求的称号(operationID)。此称号用作路由注释的最终一个参数,以界说恳求。
  • 第 4 行包括这个参数的方位(in:body,in:query 等)
  • 第 5 行是实践的内嵌结构。正如前面所说到的,你不需求一个独立的 swagger 批注包(你能够把swagger:parameters注释放在 api.CreateRepoReq 上),可是一旦你开端创立呼应注释和验证,那么在 swagger 相关批注一个独自的包会更明晰。

假如你有大的恳求,比方创立或更新,你应该创立一个新类型的变量,而不是内嵌结构。例如(留意第五元素太初行的差异):

// Request containing string
// swagger:parameters createRepoReq
type swaggerCreateRepoReq struct {
// in:body
Body api.CreateRepoReq
}

这会发生以下 SwaggerUI 恳求:

Swagger 有许多验证注释供给给 swagger:parameters和 swagger:response ,在注释标题周围的文档中有具体的描绘和运用办法。

Swagger:response [docs]

呼应注释与参数注释十分类似。首要的差异在于,经常将呼应包裹到更杂乱的结构中,所以你有必要要在 swagger 中考虑到这点。

在我的示例中,我的成功呼应如下所示:

{
"code":200, // Code containing HTTP status CODE
"data":{} // Data containing actual response data
}

尽管过错呼应有点不同:

{
"code":400, // Code containing HTTP status CODE
"message":"" // String containing error message
}

要运用惯例呼应,像上面过错呼应那样的,我通常在 swagger 包内部创立 model.go(或swagger.go)并在里边界说它们。在示例中,下面的响运用于 O运用 SwaggerUI 创立 Golang API 文档K 呼应(不回来任何数据):

// Success response
// swagger:response ok
type swaggScsResp struct {
// in:body
Body struct {
// HTTP status code 200 - OK
Code int `json:"code"`
}
}

关于过错呼应,除了称号(和示例的状况下的 HTTP 代码注释)之外,它们中的大多数类似于互相。尽管如此,你依然应该为每一个过错的状况进行界说,以便把它们作为你的端点或许的呼应:

// Error Forbidden
// swagger:response forbidden
type swaggErrForbidden struct {
// in:body
Body struct {
// HTTP status code 403 - Forbidden
Code int `json:"code"`
// Detailed error message
Message string `json:"message"`
}
}

data 中包括 model.Repository 的示例呼应:

// HTTP status code 200 and repository model in data
// swagger:response repoResp
type swaggRepoResp struct {
// in:body
Body struct {
// HTTP status code 200/201
Code int `json:"code"`
// Repository model
Data model.Repository `json:"data"`
}
}

data 中包括 model.Repository 切片的示例呼应:

// HTTP status code 200 and an array of repository models in data
// swagger:response reposResp
type swaggReposResp struct {
// in:body
Body struct {
// HTTP status code 200 - Status OK
Code int `json:"code"`
// Array of repository models
Data []model.Repository `json:"data"`
}
}

总归,这将足以生成您的 API 文档。您也应该向文档增加验证,但遵从本攻略将协助您开端。因为这首要是由我自己的经历组成,而且在某种程度上参阅了 Gitea 的源代码,我将会听取关于怎么改善这部分并相应更新的反应。

假如您有一些问题或疑问,我建议您检查怎么生成FAQ

本地运转 SwaggerUI

一旦你的注释预备就绪,你很或许会在你的本地环境中测验它。要做到这一点,你需求运转两个指令:

  1. Generate spec [docs]
  2. Serve [docs]

这个指令咱们用来生成 swagger.json 并运用 SwaggerUI:

swagger generate spec -o ./swagger.json 运用 SwaggerUI 创立 Golang API 文档--scan-models

swagger serve -F=swagger swagger.json

或许,假如你只想使它成为一个指令:

swagger generate spec -o ./swagger.json --scan-models && swagger serve -F=swagger swagger.json

履行该指令后,将运用 Petstore 保管的 SwaggerUI 翻开一个新选项卡。服务器启用了 CORS,并将标准 JSON 的 URL 作为恳求字符串附加到 petstore URL。

别的,假如运用 Redoc flavor(-F = redoc),则文档将保管在您自己的核算机上(localhost:port/docs)。

在服务器上布置

在服务器上布置生成的 SwaggerUI 有许多种办法。一旦你生成了 swagger.json,它应该相对简略地被运转。

例如,咱们的运用程序正在 Google App Eng运用 SwaggerUI 创立 Golang API 文档ine 上运转。Swagger Spec 由咱们的 CI 东西生成,并在 /docs 途径上供给。

咱们将 SwaggerUI 作为 Docker 服务布置在 GKE(Google Container/Kubernates Engine)上,它从 /docs 途径中获取swagger.json。

咱们的 CI(Wercker)脚本的一部分:

路由:

func (d *Doc) docHandler(c context.Context, w http.ResponseWriter, r *http.Request) {
r.Header.Add("Content-Type", "application/json")
data, _ := ioutil.ReadFile("/swagger.json")
w.Write(data)
}

Dockerfile:

FROM swaggerapi/swagger-ui
ENV API_URL "https://api.orga.com/swagger"

总结

SwaggerUI 是一个功能强大的 API 文档东西,能够让您轻松而美丽地记载您的 API。在 go-swagger 项目的协助下,您能够轻松地生成 SwaggerUI 所需的swagger标准文件(swagger.json)。

总归,我描绘了为完成这一方针所采纳的过程。或许有更好的办法,我会保证依据收到的反应更新这篇文章。

示例在 GitHub上可用。从示例生成的 Swagger.json 在LINK


via: https://www.ribice.ba/swagger-golang/

作者:Emir Ribic 译者:fatalc 校正:rxcai

本文由 GCTT 原创编译,Go言语中文网 荣誉推出