1.天气（JSON）

{
      "openapi": "3.1.0",
      "info": {
        "title": "Get weather data",
        "description": "Retrieves current weather data for a location.",
        "version": "v1.0.0"
      },
      "servers": [
        {
          "url": "https://weather.example.com"
        }
      ],
      "paths": {
        "/location": {
          "get": {
            "description": "Get temperature for a specific location",
            "operationId": "GetCurrentWeather",
            "parameters": [
              {
                "name": "location",
                "in": "query",
                "description": "The city and state to retrieve the weather for",
                "required": true,
                "schema": {
                  "type": "string"
                }
              }
            ],
            "deprecated": false
          }
        }
      },
      "components": {
        "schemas": {}
      }
    }

这段代码是一个OpenAPI规范的JSON文件，用于描述一个获取天气数据的API。总的来说，这个API允许用户查询特定位置的天气数据。

• "openapi": "3.1.0"：这表示使用的OpenAPI规范的版本是3.1.0。

• "info"：这部分提供了API的基本信息，包括标题、描述和版本。

• "servers"：这部分列出了API的服务器URL。

• "paths"：这部分定义了API的路径和操作。在这个例子中，有一个GET操作，路径是/location，用于获取特定位置的天气。这个操作需要一个名为location的查询参数，这个参数是必需的，类型是字符串。

• "components"：这部分用于定义API中使用的模式，但在这个例子中，它是空的。

在OpenAPI规范中，parameters是一个数组，用于定义API操作的输入参数。parameters定义了一个名为location的查询参数，这个参数是必需的，类型是字符串。每个参数都是一个对象，包含以下属性：

• "name"：参数的名称。

• "in"：参数的位置。可以是"query", "header", "path"或"cookie"。

• "description"：参数的描述。

• "required"：如果为true，则此参数是必需的。

• "schema"：参数的数据类型。

重点介绍下参数的位置，4种情况如下所示：

• header参数，用于在请求头中传递API密钥。

• path参数，用于在URL路径中指定要检索的对象的ID。

• cookie参数，用于在cookie中传递用户的会话ID。

• query参数，附加在URL后面的参数，通常用于提供信息过滤。

创建自定义工具界面：

测试工具接口界面：

2.宠物商店（YAML）

# Taken from https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore.yaml

    openapi: "3.0.0"
    info:
      version: 1.0.0
      title: Swagger Petstore
      license:
        name: MIT
    servers:
      - url: https://petstore.swagger.io/v1
    paths:
      /pets:
        get:
          summary: List all pets
          operationId: listPets
          tags:
            - pets
          parameters:
            - name: limit
              in: query
              description: How many items to return at one time (max 100)
              required: false
              schema:
                type: integer
                maximum: 100
                format: int32
          responses:
            '200':
              description: A paged array of pets
              headers:
                x-next:
                  description: A link to the next page of responses
                  schema:
                    type: string
              content:
                application/json:    
                  schema:
                    $ref: "#/components/schemas/Pets"
            default:
              description: unexpected error
              content:
                application/json:
                  schema:
                    $ref: "#/components/schemas/Error"
        post:
          summary: Create a pet
          operationId: createPets
          tags:
            - pets
          responses:
            '201':
              description: Null response
            default:
              description: unexpected error
              content:
                application/json:
                  schema:
                    $ref: "#/components/schemas/Error"
      /pets/{petId}:
        get:
          summary: Info for a specific pet
          operationId: showPetById
          tags:
            - pets
          parameters:
            - name: petId
              in: path
              required: true
              description: The id of the pet to retrieve
              schema:
                type: string
          responses:
            '200':
              description: Expected response to a valid request
              content:
                application/json:
                  schema:
                    $ref: "#/components/schemas/Pet"
            default:
              description: unexpected error
              content:
                application/json:
                  schema:
                    $ref: "#/components/schemas/Error"
    components:
      schemas:
        Pet:
          type: object
          required:
            - id
            - name
          properties:
            id:
              type: integer
              format: int64
            name:
              type: string
            tag:
              type: string
        Pets:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Pet"
        Error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: integer
              format: int32
            message:
              type: string

pet.yaml 是一个 OpenAPI 规范文件，用于描述和定义一个名为 “Swagger Petstore” 的 API 的接口。这个文件使用了 YAML 格式，它是一种用于编写配置文件的人类可读的数据序列化标准。这个文件为开发者提供了一个清晰的 API 接口定义，使得开发者可以知道如何与 “Swagger Petstore” API 进行交互。文件中的主要部分包括：

• openapi: 这个字段指定了使用的 OpenAPI 规范的版本，这里是 “3.0.0”。

• info: 这个部分提供了 API 的基本信息，包括版本、标题和许可证。

• servers: 这个部分定义了 API 的服务器 URL。

• paths: 这个部分定义了 API 的所有路径和操作。例如，/pets 路径有两个操作：get 和 post。get 操作用于列出所有宠物，post 操作用于创建一个新的宠物。每个操作都有自己的参数、响应和其他详细信息。

• components: 这个部分定义了可重用的模式（schemas），这些模式可以在 paths 部分中引用。例如，Pet、Pets 和 Error 模式。

将上述YAML文件转换为JSON格式：

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Swagger Petstore",
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://petstore.swagger.io/v1"
    }
  ],
  "paths": {
    "/pets": {
      "get": {
        "summary": "List all pets",
        "operationId": "listPets",
        "tags": ["pets"],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "How many items to return at one time (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 100,
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A paged array of pets",
            "headers": {
              "x-next": {
                "description": "A link to the next page of responses",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pets"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a pet",
        "operationId": "createPets",
        "tags": ["pets"],
        "responses": {
          "201": {
            "description": "Null response"
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/pets/{petId}": {
      "get": {
        "summary": "Info for a specific pet",
        "operationId": "showPetById",
        "tags": ["pets"],
        "parameters": [
          {
            "name": "petId",
            "in": "path",
            "required": true,
            "description": "The id of the pet to retrieve",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Expected response to a valid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pet": {
        "type": "object",
        "required": ["id", "name"],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "name": {
            "type": "string"
          },
          "tag": {
            "type": "string"
          }
        }
      },
      "Pets": {
        "type": "array",
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/Pet"
        }
      },
      "Error": {
        "type": "object",
        "required": ["code", "message"],
        "properties": {
          "code": {
            "type": "integer",
            "format": "int32"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}

3.空白模板

{
      "openapi": "3.1.0",
      "info": {
        "title": "Untitled",
        "description": "Your OpenAPI specification",
        "version": "v1.0.0"
      },
      "servers": [
        {
          "url": ""
        }
      ],
      "paths": {},
      "components": {
        "schemas": {}
      }
    }

注解：貌似JSON格式看上去更加直观。

参考文献

[1] OpenAPI Specification：https://swagger.io/specification/