用Swagger写一份优雅API文档

Posted on | Edited on | In | Comments: | Views:
初次尝试

前言

最近要做一些小的课程项目, 然后又是负责服务端这部分的, 所以要写一份优雅的API文档, 减少整个团队的沟通成本(同时也真的挺好看/用的)

目标

因为项目代码是在 Github 进行托管的, 所以最后也是利用 Github Page 显示出来

效果:

开始

我用的是Swagger 在线编辑, 加载可能有点慢, 然后就动手尝试写吧, 右边的渲染界面会马上把修改后的内容渲染出来

或者看下面我对写yaml的一些理解, 主要是分成几个块来写

顶端部分

这里是最后的 Swagger UI 的顶端部分, 我去掉了一些用不到的代码, 大概用以下地方完成:

有个比较坑的地方, 下面这里是在代码最后的部分= =

API模块

当然还有通信协议 HTTP 和 HTTPS(或者其他?)

是下面这部分代码写成的:

具体API接口


这接口根本一点都不 RESTful 啊, 对, 作者太菜了, 还要学习学习

接口是写在 paths 这里的:

register 代码: 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
/account/register:            # 路径
  post:                       # 方法
    tags:                     # 属于哪个API模块
    - "account"
    summary: "注册账户"
    consumes:
    - "application/json"      # 请求类型
    produces:
    - "application/json"      # 返回类型
    parameters:               # 参数, 没有则删除这段
    - in: "body"
      name: "body"
      description: "注册信息"
      required: true
      schema:
        $ref: "#/definitions/User" # 这里要加载你定义的model, 下面再说
    responses:                     # 响应回复
      200:
        description: "能够处理的请求"
        schema:
          $ref: '#/definitions/returnMessage'
      404:
        description: "不能处理的请求"

logout 代码: 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/account/logout:
  get:
    tags:
    - "account"
    summary: "登出"
    consumes:
    - "application/json"
    produces:
    - "application/json"
    responses:
      200:
        description: "能够处理的请求"
        schema:
          $ref: '#/definitions/returnMessage'
      404:
        description: "不能处理的请求"

model

这里写的东西就是为 API 接口服务的, 便于更好的显示


大概这么写:

注意一下, xml 是给这个 model 定义一个名字, 然后在上面就可以引用这个名字来显示了

然后

写写写, 写多一会就写好了, 写完了就把 yaml 文件下载下来吧

Github page 设置

首先

我是在项目 repository 的 master 分支根目录新建了文件夹 /docs, 你也可以新开一个 repository 来显示, 都没关系

然后在 repository 的 setting 中选好 GitHub Pages 的 Source

但是 /docs 里根本没有东西啊! 对, 接下来放一些东西进去

放网页到 docs

找一个地方, 把 swagger-ui clone 下来 

1
git clone https://github.com/swagger-api/swagger-ui.git

然后把这个项目的 dist 文件夹里的全部文件复制到刚刚弄好的 docs/ 里, 还有之前写好的 yaml 文件

编辑这里的 index.html 文件, 把 url 字段的内容换成你的 yaml 文件

push到仓库, 完成!

git 三连 

1
2
3
git add .
git commit -m "add docs"
git push

push 完成后, 稍等一会(大概10分钟), 访问你的 Github Page 就可以看到啦

或者, 访问你的 Github Page 后面加 index.html 可以马上看到效果

这里是我刚写这份博客的时候写好的 API 文档, 不是很好哈哈哈

资料备查

yaml语法说明

太长建议有需要的时候再查

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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
swagger: '2.0'                      # swagger的版本
info:
  title: 文档标题
  description:  描述
  version: "v1.0"                   # 版本号
  termsOfService: ""                # 文档支持截止日期
  contact:                          # 联系人的信息
    name: ""                        # 联系人姓名
    url: ""                         # 联系人URL
    email: ""                       # 联系人邮箱
  license:                          # 授权信息
    name: ""                        # 授权名称，例如Apache 2.0
    url: ""                         # 授权URL
host: api.haofly.net                # 域名，可以包含端口，如果不提供host，那么默认为提供yaml文件的host
basePath: /                         # 前缀，比如/v1
schemes:                            # 传输协议
  - http
  - https

securityDefinitions:                # 安全设置
  api_key:
    type: apiKey
    name: Authorization             # 实际的变量名比如，Authorization
    in: header                      # 认证变量放在哪里，query或者header
  OauthSecurity:                    # oauth2的话有些参数必须写全
    type: oauth2
    flow: accessCode                # 可选值为implicit/password/application/accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'
    scopes:
      admin: Admin scope
      user: User scope
      media: Media scope
  auth:
    type: oauth2
    description: ""                 # 描述
    authorizationUrl: http://haofly.net/api/oauth/
    name: Authorization             # 实际的变量名比如，Authorization
    tokenUrl:
    flow: implicit                  # oauth2认证的几种形式，implicit/password/application/accessCode
    scopes:
      write:post: 修改文件
      read:post: 读取文章

security:                           # 全局的安全设置的一个选择吧
  auth:
    - write:pets
    - read:pets

consumes:                           # 接收的MIME types列表
  - application/json                # 接收响应的Content-Type
  - application/vnd.github.v3+json

produces:                           # 请求的MIME types列表
  - application/vnd.knight.v1+json  # 请求头的Accept值
  - text/plain; charset=utf-8
tags:                               # 相当于一个分类
  - name: post  
    description: 关于post的接口

externalDocs:
  description: find more info here
  url: https://haofly.net

paths:                              # 定义接口的url的详细信息
  /projects/{projectName}:          # 接口后缀，可以定义参数
    get:
      tags:                         # 所属分类的列表
        - post  
      summary: 接口描述              # 简介
      description:                  # 详细介绍
      externalDocs:                 # 这里也可以加这个
        description:
        url:
      operationId: ""               # 操作的唯一ID
      consumes: [string]            # 可接收的mime type列表
      produces: [string]            # 可发送的mime type列表
      schemes: [string]             # 可接收的协议列表
      deprecated: false             # 该接口是否已经弃用
      security:                     # OAuth2认证用
        - auth: 
            - write:post
            - read: read
      parameters:                   # 接口的参数
        - name: projectName         # 参数名
          in: path                  # 该参数应该在哪个地方，例如path、body、query等，但是需要注意的是如果in body，只能用schema来指向一个定义好的object，而不能直接在这里定义
          type: string              # 参数类型
          allowEmptyValue: boolean          # 是否允许为空值
          description: 项目名        # 参数描述
          required: true            # 是否必须
          default: *                # 设置默认值
          maximum: number           # number的最大值
          exclusiveMaximum: boolean # 是否排除最大的那个值
          minimum: number           # number的最小值
          exclusiveMinimum: boolean
          maxLength: integer        # int的最大值
          minLength: integer
          enum: [*]                 # 枚举值
          items:                    # type为数组的时候可以定义其项目的类型
        - $ref: "#/parameters/uuidParam"   # 这样可以直接用定义好的
      responses:                    # 设置响应
        200:                        # 通过http状态来描述响应
          description: Success      # 该响应的描述
          schema:                   # 定义返回数据的结构
            $ref: '#/definitions/ProjectDataResponse'  # 直接关联至某个model

  /another: # 另一个接口
      responses:
        200:
            description:
            schema:
              type: object
              properitis:
                data:
                    $ref: '#/definitions/User' # 关联

definitions:            # Model/Response的定义，这里的定义不强制要求返回数据必须和这个一致，但是在swagger-ui上，会展示这里面的字段。
  Product:              # 定义一个model
    type: object        # model类型
    properties:         # 字段列表
      product_id:       # 字段名
        type: integer   # 字段类型
        description:    # 字段描述
      product_name:
        type: string
        description: 
  ProjectDataResponse:
    type: object
    properties:
        data:
            $ref: '#/definitions/ProjectResponse'  # model之间的关联，表示在data字段里面包含的是一个ProjectResponse对象
parameters:             # 可以供很多接口使用的params
  limitParam:
    name: limit
    in: query
    description: max records to return
    required: true
    type: integer
    format: int32
responses:              # 可以供很多接口使用的responses
  NotFound:
    description: Entity not found.

参考

Swagger Edit 安装和使用教程