说明

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swag

在开始使用swagger之前，需要安装swag

  1. // 下载地址
  2. https://github.com/swaggo/swag

示例

  • 项目说明首先通过注解，表明接口的基础请求地址为：localhost:8080/`

    1. // @title Swagger Example API
    2. // @version 1.0
    3. // @description This is a sample server Petstore server.
    4. // @termsOfService http://swagger.io/terms/
    5. // @contact.name hongker
    6. // @contact.url http://hongker.github.io
    7. // @contact.email xiaok2013@live.com
    8. // @license.name Apache 2.0
    9. // @license.url http://www.apache.org/licenses/LICENSE-2.0.html
    10. // @host localhost:8080
    11. // @BasePath /
    12. func main()  {
    13.   // ...
    14. }

  • 接口说明 声明接口的相关信息，访问路由为: /user/auth

    1. // UserAuthHandler 用户登录
    2. // @Summary 用户登录
    3. // @Description 通过邮箱和密码登录，换取token
    4. // @Accept  json
    5. // @Produce json
    6. // @Param email body string true "邮箱"
    7. // @Param pass body string true "密码"
    8. // @Success 0 "success"
    9. // @Failure 500 "error"
    10. // @Router /user/auth [post]
    11. func UserAuthHandler(ctx *gin.Context) {
    12.   // demo
    13. }

    各项注解说明：

    1. Summary : 副标题
    2. Description : 接口描述
    3. Accept : 接收类型
    4. Produce: 响应类型
    5. Param: 参数
    6. Success: 成功的响应
    7. Failure: 失败的响应
    8. Router : 路由(包括uri, method)

  • 使用swag生成文档

    1. swag init

    通过以上命令即可在项目目录下生成一个docs目录

开启swagger

  • 配置

    1. http:
    2.   swagger: on

  • 路由

    1. import (
    2.   _ "demo/docs" // 这行不能少
    3. )
    4. // 通过 {host}/swagger/index.html访问swagger web