SwaggerAPI intro

发表于 分类于 阅读次数： 本文字数： 1.4k 阅读时长 ≈ 1 分钟

Swagger

Swagger是一套围绕OpenAPI规范构建的开源工具,可以设计·构建·编写·使用RESTAPI

  • Swagger编辑器:
  • Swagger UI: 将OpenAPI规范呈现为交互式API文档，并可以在浏览器中尝试API调用
  • Swagger Codegen: 根据OpenAPI规范，生成服务器存根和客户端代码库

Swagger和OpenAPI区别

  • OpenAPI
    1
    OpenAPI是一个API规范，前身是Swagger规范. Swagger是实现规范的工具

go-swagger生成Swagger API 文档

  • go-swagger特征

    1
    2
    3
    4
    5
    1. 根据Swagger定义文件生成服务端代码
    2. 根据Swagger定义文件生成客户端代码
    3. 校验Swagger定义文件是否正确
    4. 启动一个HTTP服务器，使我们可以通过浏览器访问API文档
    5. 根据Swagger文档定义的参数生成Go Model结构体定义

  • Swagger工具

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    github.com/chyidl/noone via 🐹 v1.17
    ➜ go get -u github.com/go-swagger/go-swagger/cmd/swagger

    github.com/chyidl/noone via 🐹 v1.17 took 25s
    ➜ swagger version
    version: v0.27.0
    commit: (unknown, mod sum: "h1:K7+nkBuf4oS1jTBrdvWqYFpqD69V5CN8HamZzCDDhAI=")

    github.com/chyidl/go-swagger-demo via 🐹 v1.17
    ➜ swagger generate spec -o swagger.yaml
      -o: 指定输出文件名

    github.com/chyidl/go-swagger-demo via 🐹 v1.17
    ➜ ls
    api          docs         go.mod       main.go      swagger.yaml
    github.com/chyidl/go-swagger-demo via 🐹 v1.17
    ➜ swagger serve --no-open -F=swagger --port 36666 swagger.yaml
    2021/09/09 12:58:09 serving docs at http://localhost:36666/docs
      --no-open: 禁止调用浏览器打开
      -F: 指定文档风格
      --port: 指定启动的HTTP服务监听

    github.com/chyidl/go-swagger-demo via 🐹 v1.17
    ➜ swagger generate spec -i ./swagger.yaml -o ./swagger.json

    // swagger:route POST /users user createUserRequest
    // Create a user in memory.
    // responses:
    //   200: createUserResponse
    //   default: errResponse

    // swagger:route GET /users/{name} user getUserRequest
    // Get a user from memory.
    // responses:
    //   200: getUserResponse
    //   default: errResponse