5775发表于 2020-01-01 18:00:37
只看该作者楼主

如何写出规范可读的接口文档 [复制链接]

本帖最后由 2020-01-03 13:16:27 编辑

工具

swagger2.0

简介 

swagger是一个简单、功能强大的API表达工具。

编写语言

编写swagger的接口描述推荐使用yaml语法。

实战

定义api操作:getpostputdelete

http协议中多种不同方法类型,get用于获取资源post用于新增资源put用于修改资源delete用于删除资源(optionstraceconnecthead不做描述)

定义api参数:querypathbodyformheader

query表示将请求参数拼接在url后面,path则表示将请求参数嵌入到url之中,body表示将请求参数放到请求体中,form表示将请求数据以form的形式放入请求体中,header表示将请求参数放入到请求头里面。

query例子:/persons?name=xxx

/persons:
  get:
    tags:
    - Person
    parameters:
    - name: name
      in: query
      type: string
    responses:
      200:
        description: 成功

path例子:/persons/1001

/persons/{id}:
  get:
    tags:
    - Person
    parameters:
    - name: id
      in: query
      type: integer
      format: int64
      required: true
    responses:
      200:
        description: 成功

body例子:/persons

/persons:
  post:
    tags:
    - Person
    parameters:
      - name: person
      in: body
      schema:
        $ref: '#/definitions/Person'
    responses:
      200:
      description: OK

form例子:/persons

/persons:
  post:
    consumes:
    - application/x-www-form-urlencoded
    - multipart/form-data
    parameters:
    - name: username
      type: string
      in: formData
    - name: password
      type: string
      in: formData
    responses:
      200:
      description: OK

header例子: /persons

/persons:
  get:
    tags:
    - Person
    parameters:
      - name: xxx-token
      type: string
      in: header
    responses:
      200:
      description: 成功

 

模型定义

swagger中提供了模型定义的能力,通过定义模型可以来描述复杂的对象。

简单参数定义

parameters:
  username:
    name: username
    type: string
    in: query

使用方式只需在parameters:标签下加入-$ref:’#/parameters/username’即可。

复杂参数定义

Person:
    properties:
        username:
            type: string
        id:
            type: integer
            format: int64
        password:
            type: string

使用方式只需在schema:标签下加入$ref:’#/definitions/Person’即可。

响应参数定义

responses:
  OK:
    description: 成功
    schema:
      $ref: '#/definitions/Person'

使用方式只需在200:等标签下加入$ref:’#/responses/OK’即可。


除了以上的内容之外,我们还可以通过如下的内容来增强接口的可读性

          给所有的字段、模型都加上description信息。

          给模型定义中的所有属性都加上example字段来增强可读性。

          对于可枚举的内容最好加上枚举属性。

          对于有上下限的数据最好给定上下限(minimummaximum)。

          对于日期类型使用type:string, format: date/date-time来描述。

          如果对集合的大小和元素唯一性有限制,使用minItems/maxItems/uniqueItem来进行限制。

          如果是模型中有只读属性,需要设置为只读readOnly

          如果需要使用聚集属性,可以在模型中使用allOf: -$ref:的形式来聚集两个模型的属性。

    definitions:
       PagedePersons:
         allOf:
         - $ref: '#/definitions/PageBean'
         - $ref: '#/definitions/Persons'

          如果参数有默认值,可以使用default:来设置默认值。

    age:
       type: integer
       default: 18
       maximum: 100
       minimum: 0

          如果需要使用参数组来批量查询,可以使用collectionFormat: csv/ssv/tsv/pipes/multi来传递批量查询的参数。

     ids:
       name: ids
       type: array
       in: query
       collectionFormat: csv  

鉴权

如果项目中涉及到鉴权,使用securityDefinitions:来进行鉴权定义。

securityDefinitions:
  BasicSecurity:
    type: basic
  AdminSecurity:
    type: apiKey
    in: header
    name: ADMIN-API-KEY
  OauthSecurity:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://xxx.com/auth'
    tokenUrl: 'https://xxx.com/token'
    scopes:
      admin: ADMIN SCOPE
      user: USER SCOPE

鉴权的使用可以是API级别,也可以是操作级别,对于API级别的鉴权,直接与paths:节点同级进行配置即可,对于操作级别的鉴权,需要在get/post等方法的下级节点进行配置。


API级别鉴权

security:
- BasicSecurity: []

操作级别鉴权

path:

 ...

 get:

   security:
      - BasicSecurity: []
      - OauthSecurity: []

 

以上内容可以非常方便的定义接口,但是还有更加重要的一点就是url自身的可读性,在当前微服务盛行的浪潮下。对于CRUD类型的接口,我们可以使用swagger提供的上述特性来定义url,使用如下的restful风格的接口定义可以将借口进行资源化。

@DELETE(“/persons/{id}”)

@GET(“/persons/{id}”)

@POST(“/persons”)

@PUT(“/persons”)

对于None-CRUD类型的接口,比如数据库开启和关闭,如何优雅的写出对应的url呢?/openDatabase吗?实际上我们仍然可以将数据库的操作变成restful的风格。

如:开启数据库使用/db?command=open, 关闭数据库使用/db?command=shutdown


发表于 2020-01-02 09:53:28
只看该作者沙发

总结的真心不错,学习了

发表于 2020-01-03 11:06:20
只看该作者板凳

新人帖,支持一下。。


发表于 2020-01-21 10:31:06
只看该作者地板

关联阅读:分布式系统概念

发表于 2020-01-21 10:31:17
只看该作者5 #

关联阅读:分布式数据分布

发表于 2020-01-21 10:31:46
只看该作者6 #

您需要登录后才可以回帖

登录注册
发表回复