主页

索引

模块索引

搜索页面

3.5.3. Swagger

备注

我开始一直不理解，浪费很多时间的地方，swagger对业务侵入比较大，这样做的目的是：通过 Swagger UI 页面,API 使用者可以更直观地查看 API、进行调试与调用,而不仅仅是阅读文字文档。另外，好多使用方法是根据配置文件来自动生成对应代码。

降低耦合的方法:

1. 将 Swagger 相关逻辑提取出来,放在单独的文件中,仅在 main() 中加载调用
2. 使用中间件而非在主函数直接加载 Swagger
3. Swagger 文档作为独立服务部署
4. 采用 OpenAPI 规范,而不 tight 绑定到 Swagger

swaggo✅

安装:

go get -u github.com/swaggo/swag/cmd/swag

使用:

$ swag -v

$ swag init -g <filename>.go -d <folder>
// 说明:
        生成目录 docs
        -g/--generalInfo: 指定入口文件名(默认main.go)
        -d/--dir: 指定入口文件路径(默认.)


// 生成MarkDown文档
$ swag init --md .

备注

要想生成gin等框架的项目，需要特别处理。

参考

go-swagger

安装:

docker pull quay.io/goswagger/swagger
alias swagger='docker run --rm -it  --user $(id -u):$(id -g) -e GOPATH=$(go env GOPATH):/go -v $HOME:$HOME -w $(pwd) quay.io/goswagger/swagger'


安装go-swagger工具:
go install github.com/go-swagger/go-swagger/cmd/swagger

实例化:

swagger init spec \
  --title "A Todo list application" \
  --description "From the todo list tutorial on goswagger.io" \
  --version 1.0.0 \
  --scheme http

验证:

swagger validate ./swagger.yml

生成:

// 生成 Swagger 文档
swagger generate spec -o ./swagger.json
swagger generate spec -f ./swagger.yml -o ./swagger.json

基于配置文件生成服务器golang代码:

$ swagger generate server -A <name> -f ./swagger.yml

Generate spec markdown spec:

swagger generate markdown -f {spec} --output swagger.mode

基于swagger.yml启动文档服务:

$ swagger serve  -p 7777 --path=docs ./folder/swagger.yaml

示例

初使化配置&生成服务器代码:

1. 生成文件swagger.yml
$ swagger init spec \
  --title "A Todo list application" \
  --description "From the todo list tutorial on goswagger.io" \
  --version 1.0.0 \
  --scheme http \
  --consumes application/io.goswagger.examples.todo-list.v1+json \
  --produces application/io.goswagger.examples.todo-list.v1+json

2. 修改swagger.yml 添加相关接口
3. 生成相关代码::
$ swagger generate server -A <name> -f ./swagger.yml

生成代码目录结构:
├── cmd
│   └── todo-list-server
│       └── main.go
├── models
│   ├── error.go
│   ├── get_okbody.go
│   └── item.go
├── restapi
│   ├── configure_todo_list.go
│   ├── doc.go
│   ├── embedded_spec.go
│   ├── operations
│   │   ├── todo_list_api.go
│   │   └── todos
│   │       ├── get.go
│   │       ├── get_parameters.go
│   │       ├── get_responses.go
│   │       └── get_urlbuilder.go
│   └── server.go
└── swagger.yml

参考

Swagger UI

使用:

docker run -p 7080:8080 -e SWAGGER_JSON=/foo/swagger.json -v ${pwd}:/foo swaggerapi/swagger-ui

docker run -p 7080:8080 -e SWAGGER_JSON_URL=https://petstore3.swagger.io/api/v3/openapi.json swaggerapi/swagger-ui

主页

索引

模块索引

搜索页面