OpenAPI 规范总结

一、openapi.yaml 代码示例：

openapi: 3.0.3
info:
  title: Sample Pet Store App 2.0
  description: |
    This is a sample server for a pet store.

    # Test technologies
    - Test 1
    - Test 2
    - Test 3

    # Important
    HTTPS only. RESTful, resource oriented

    # Get Started
    Set up your APIs or get authorization

    # Request and Response
    application/json

    # Support
    [Sandbox Hub](https://test.com/sandbox)
  termsOfService: 'http://example.com/terms/'
  license:
    name: Apache 2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
  version: 1.0.0
servers:
  - url: 'https://development.gigantic-server.com/v1'
    description: Development server
  - url: 'https://dev.test.com/v2'
    description: Development environment
tags:
  - name: pet
    description: Pets operations.
  - name: Accounts
    description: Operations related to user's account info.
paths:
  /wallets:
    post:
      tags:
        - Wallets
      operationId: create_wallet
      summary: Create new wallet
      description: ..More detailed explanation on creating a new wallet..
      security:
        - OAuth2:
            - 'wallets:write'
            - admin
        - CoboAuth: []
          CoboSignature: []
          CoboNonce: []
        - CookieAuth: []
      parameters:
        - $ref: '#/components/parameters/orgIdQueryParam'
      requestBody:
        $ref: '#/components/requestBodies/createWalletBody'
      responses:
        '201':
          $ref: '#/components/responses/createWalletResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
    get:
      tags:
        - Wallets
      operationId: list_wallets
      summary: List all wallets
      description: Retrieve a list of wallets.
      security:
        - OAuth2:
            - 'wallets:read'
            - admin
        - CoboAuth: []
          CoboSignature: []
          CoboNonce: []
        - CookieAuth: []
      parameters:
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/filterByType'
        - $ref: '#/components/parameters/orgIdQueryParam'
      responses:
        '200':
          $ref: '#/components/responses/getWalletsApi'

二、字段释义

1. openapi：版本号，必选. 该字段应该被工具或者客户端用来解释 OpenAPI 文档

2. info：提供API相关的元数据，必选

  1) title: 应用的名称。必选.

  2) description：对应用的简短描述

  3) version：API文档的版本信息，必选.

3. servers：Server对象的数组， 提供到服务器的连接信息

4. tags：提供更多元数据的一系列标签

5. paths：对所提供的API有效的路径和操作。必选。

三、Paths对象

描述对路径的某个操作

1. tags：用于控制API文档的标签列表，标签可以用于在逻辑上分组对资源的操作或作为其它用途的先决条件

2. operationId：用于标识此操作的唯一字符串，这个id在此API内包含的所有操作中必须是唯一的

3. summary：对此操作行为的简短描述

4. description：对此操作行为的详细解释

5. security：声明安全机制

6. parameters：定义可用于此操作的参数列表

7. requestBody：可用于此操作的请求体

8. responses：必选.定义执行此操作后的可能的响应值列表