Swagger从入门到放弃

如何编写基于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/#
``YAML swagger: "2.0" info: description: "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key \special-key` to test the authorization filters."
version: "1.0.0"
title: "Swagger Petstore"
termsOfService: "http://swagger.io/terms/"
contact:
email: "[email protected]"
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、主机名、根路径来描述：
YAML 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

Swagger从入门到放弃

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

简介

从零开始

高级定义

猜你喜欢