Swagger从入门到放弃 - 生如夏花2017

公告

如何编写基于OpenAPI规范的API文档

简介

Swagger
Swagger是一个简单但功能强大的API表达工具。支持的语言种类繁多
使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性
OpenAPI规范
OpenAPI规范是Linux基金会的一个项目，试图定义一种用来描述API格式或API定义的语言，来规范RESTful服务的开发过程
OpenAPI可以帮助我们描述一个API的基本信息：
- 有关API的一般性描述
- 可用路径
- 在每个路径上的可用操作
- 每个操作的输入输出格式
OpenAPI规范这类API定义语言能够更简单、快速的表述API，尤其是在API设计阶段作用比较明显
如何编写API文档
编辑器采用在线编辑：https://editor.swagger.io/#

      swagger: "2.0"
      info:
      description: 
      version: "1.0.0"
      title: "Swagger Petstore"
      termsOfService: "http://swagger.io/terms/"
      contact:
          email: "apiteam@swagger.io"
      license:
          name: "Apache 2.0"
          url: "http://www.apache.org/licenses/LICENSE-2.0.html"
      host: "petstore.swagger.io"
      basePath: "/v2"
      tags:
      - name: "pet"
      description: "Everything about your Pets"
      externalDocs:
          description: "Find out more"
          url: "http://swagger.io"
      - name: "store"
      description: "Access to Petstore orders"
      - name: "user"
      description: "Operations about user"
      externalDocs:
          description: "Find out more about our store"
          url: "http://swagger.io"
      schemes:
      - "http"
      paths:
          /pet:
              post:
              tags:
                  - "pet"
              summary: "Add a new pet to the store"
              description: ""
              operationId: "addPet"
              consumes:
                  - "application/json"
                  - "application/xml"
              produces:
                  - "application/xml"
                  - "application/json"
              parameters:
                  -   in: "body"
                      name: "body"
                      description: "Pet object that needs to be added to the store"
                      required: true
                      schema:
                      $ref: "#/definitions/Pet"
              responses:
                  405:
                  description: "Invalid input"
              security:
              - petstore_auth:
                  - "write:pets"
                  - "read:pets"

从零开始

  swagger: '2.0'
  info:
  version: 1.0.0
  title: Simple API
  description: A simple API documentation

  schemes: 
  - https
  host: simple.api
  basePath: /openapi101
  paths:
  {}

显示界面如下：
首先要通过swagger属性来声明OpenAPI规范的版本
然后需要说明API文档的相关信息，比如API文档版本、API文档名称、描述信息等
最后作为webURL，一个很重要的信息就是用来给消费者使用的根URL ，可以使用协议http或https、主机名、根路径来描述：
```
    schemes: 
    - https
    host: simple.api
    basePath: /openapi101
    ```
```
接下来就是写API的操作，通过paths，然而这里没有写只是通过{}对象占用位置

  swagger: '2.0'
  info:
  version: 1.0.0
  title: Simple API
  description: A simple API documentation

  schemes: 
  - https
  host: simple.api
  basePath: /openapi101
  paths:
  /persons:
      get:
      summary: Get some persons
      description: Returns a list containing all persons
      responses:
          200:
              description: A list of Person
              schema:
                  type: array
                  items:
                      required: 
                          - username
                      properties:
                          firstname:
                              type: string
                          lastname:
                              type: string
                          username:
                              type: string

在上面的这些代码中，做了以下的动作：
1. 添加了/persons的路径，用来访问一组用户信息
2. 在路径中添加了HTTP方法get，同时也有一些简单的描述信息summary和description
3. 定义响应类型responses，响应类型中添加了HTTP状态码200
4. 定义了响应内容：通过响应消息中的schema属性来描述清楚具体的返回内容。通过type属性可知一组用户信息就是一个用户信息数组，每一个数组元素则是一个用户对象，该对象包含三个string类型的属性，其中username必须提供（required）
定义请求参数

  paths:
  /persons:
      get:
      summary: Get some persons
      description: Returns a list containing all persons
      parameters: 
          -   name: pageSize
              in: query
              description: Number of persons returned
              type: integer
          -   name: pageNumber
              in: query
              description: Page number
              type: integer

首先在get方法中添加了一个parameters属性
在参数列表中，添加了两个参数pageSize和pageNumber的整形参数，并有简单描述
定义路径参数

  swagger: '2.0'
  info:
  version: 1.0.0
  title: Simple API
  description: A simple API documentation

  schemes: 
  - https
  host: simple.api
  basePath: /openapi101
  paths:
  /persons/{username}:
      get:
      summary: Get some persons
      description: Returns a list containing all persons
      parameters: 
          -   name: username
              in: path
              required: true
              description: The person's username
              type: string
          
      responses:
          200:
          description: A list of Person
          schema:
              type: array
              items:
                  required: 
                      - username
                  properties:
                      firstname:
                          type: string
                      lastname:
                          type: string
                      username:
                          type: string

路径参数、请求参数以及消息参数等的不同之处就在于in属性的值不同，分别为path、query、body等。同时对于参数的类型可以使用type或者schema来定义，例如消息体参数如下：

  swagger: '2.0'
  info:
  version: 1.0.0
  title: Simple API
  description: A simple API documentation

  schemes: 
  - https
  host: simple.api
  basePath: /openapi101
  paths:
      /persons:
          post:
          summary: Creates a person
          description: Adds a new person to the persons list
          parameters: 
              -   name: person
                  in: body
                  description: The person to create
                  schema:
                      required: 
                      - username
                      properties:
                          firstname:
                              type: string
                          lastname:
                              type: string
                          username:
                              type: string
          responses:
              200:
              description: OK

如果是单个参数可以使用type进行定义例如integer，string ，array等，而如果是json类型的参数就需要使用schema类来定义。
定义相应消息

  response:
      204:
          description:Persons successfully created
      400:
          description:Persons couldn't have been created

简化数据模型
通过使用definition来定义可重用的对象。如下：

  swagger: '2.0'
  info:
  version: 1.0.0
  title: Simple API
  description: A simple API documentation

  schemes: 
  - https
  host: simple.api
  basePath: /openapi101
  paths:
  /persons:
      post:
      summary: Creates a person
      description: Adds a new person to the persons list
      parameters: 
          -   name: person
              in: body
              description: The person to create
              schema:
                  $ref: '#/definitions/Person'
      responses:
          200:
          description: OK
          schema:
              $ref: "#/definitions/Person"
          
  definitions:
      Person:
          required:
              - username
          properties:
              firstname:
                  type: string
              lastname: 
                  type: string
              username:
                  type: string

定义可重用的参数

  swagger: '2.0'
  info:
  version: 1.0.0
  title: Simple API
  description: A simple API documentation

  schemes: 
  - https
  host: simple.api
  basePath: /openapi101
  paths:
      /persons/{username}:
          get:
              parameters: 
                  - $ref: '#/parameters/username'
          
              responses:
                  200:
                  description: fsafsf

  parameters:
      username:
          name: username
          in: path
          required: true
          description: The person's username
          type: string

高级定义

字符串的长度和格式

  -   name: username
      in: path
      required: true
      description: fasfsa
      type: string
      pattern: "[a-z0-9]{8,64}"
      minLength: 8
      maxLength: 64

日期和时间

  parameters: 
      - name: dateofBirth
        in: query
        description: fasfsaf
        type: string
        format: date

枚举类型

  code:
      type: string
      enum: 
          - DBERR
          - NTERR
          - UNERR

高级参数
参数的媒体类型
在文档的根节点下面添加：

  produces:
      - text/xml
  consumes:
      - application/json
      - application/xml

高级响应消息
要定义一个不带消息体的相应消息，只需要写响应状态和描述即可

  responses:
      '204':
          description: Person successfully created

与请求消息类似，必带参数使用required来标识

  Person:
      required:
          - username
      properties:
          firstname:
              type: string
          lastname: 
              type: string
          username: 
              type: string

分类标签
tags: - Persons

posted on 2018-05-04 10:54 生如夏花2017 阅读(3367) 评论(0) 编辑收藏举报

会员力量，点亮园子希望

刷新页面返回顶部