swagger应用【转】5分钟了解Swagger

1. swagger简述

swagger定义了一套接口文件的规范，是一个API文档架构。接口规范swagger2.0（aka openAPI 2.0），https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md。

使用Swagger，就是把相关的API信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

生成yaml或json描述文档的方法：可以手动编辑（通过swagger-editor或vim等）；也可在代码中增加规则指定的注释，然后利用工具自动生成json或yaml。

swagger提供的工具：

Swagger Editor： Swagger描述文件的编辑器，支持实时更新。也提供了在线编辑器和本地部署编辑器两种方式。

Swagger UI：提供了一个可视化的UI页面展示描述文件，可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。

Swagger Inspector: 一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

2. go-swagger

github: https://github.com/go-swagger/go-swagger.git

使用说明参考： https://goswagger.io/

安装

go build -o swagger cmd/swagger/swagger.go
cp swagger ~/go/bin

使用

$ swagger -h
Usage:
  swagger [OPTIONS] <command>

Swagger tries to support you as best as possible when building APIs.

It aims to represent the contract of your API with a language agnostic description of
your application in json or yaml.

Application Options:
  -q, --quiet                  silence logs
      --log-output=LOG-FILE    redirect logs to file

Help Options:
  -h, --help                   Show this help message

Available commands:
  diff      diff swagger documents
  expand    expand $ref fields in a swagger spec
  flatten   flattens a swagger document
  generate  generate go code
  init      initialize a spec document
  mixin     merge swagger documents
  serve     serve spec and docs
  validate  validate the swagger document
  version   print the version

校验

swagger validate autodoc.yml

UI server

其中参数--no-open是为了限制客户端的界面打开（因为多数时候服务都是后台console执行）

swagger serve --host=0.0.0.0 --port=2399 --no-open autodoc.yml

服务端code

swagger generate server [-f ./swagger.json] -A [application-name [--principal [principal-name]]

客户端code

swagger generate client [-f ./swagger.json] -A [application-name [--principal [principal-name]]

参考：

1. 【转】5分钟了解Swagger

2. golang restful 框架之 go-swagger

3. 使用 SwaggerUI 创建 Golang API 文档