Swagger从入门到放弃

时间 2019-11-09

标签 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/#

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、主机名、根路径来描述：
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

1. Kettle从入门到放弃
2. Swift从入门到放弃
3. 从入门到放弃
4. Openstack从入门到放弃
5. Lombok从入门到放弃
6. HTTP从入门到放弃
7. ElasticSearch从入门到放弃
8. Maven从入门到放弃
9. git从入门到放弃
10. Django从入门到放弃
更多相关文章...
• Memcached入门教程 - NoSQL教程
• Neo4j数据库入门教程 - NoSQL教程
• YAML 入门教程
• Java Agent入门实战（一）-Instrumentation介绍与使用