[TOC] > [官方说明](https://swagger.io/docs/specification/basic-structure/) ## 概述 对 swagger.yaml 文件是说明 ## 基本说明 ``` openapi: 3.0.0 info: title: Sample API description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML. version: 0.1.9 servers: - url: http://api.example.com/v1 description: Optional server description, e.g. Main (production) server - url: http://staging-api.example.com description: Optional server description, e.g. Internal staging server for testing paths: /users: get: summary: Returns a list of users. description: Optional extended description in CommonMark or HTML. responses: '200': # status code description: A JSON array of user names content: application/json: schema: type: array items: type: string ``` ## 元数据 ``` openapi:3.0.0 info: title: Sample API description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML. version: 0.1.9 ``` ## 服务器列表 > [详细说明](https://swagger.io/docs/specification/api-host-and-base-path/) ``` servers: - url: http://api.example.com/v1 description: Optional server description, e.g. Main (production) server - url: http://staging-api.example.com description: Optional server description, e.g. Internal staging server for testing ``` 可以定义一个或多个服务器，例如生产和沙盒 ## 路径 > [详细说明](https://swagger.io/docs/specification/paths-and-operations/) ``` paths: /users: get: summary: Returns a list of users. description: Optional extended description in CommonMark or HTML responses: '200': description: A JSON array of user names content: application/json: schema: type: array items: type: string ``` ## 参数 > [详细说明](https://swagger.io/docs/specification/describing-parameters/) ``` paths: /users/{userId}: get: summary: Returns a user by ID. parameters: - name: userId in: path required: true description: Parameter description in CommonMark or HTML. schema: type : integer format: int64 minimum: 1 responses: '200': description: OK ``` 操作可以通过 URL 路径 (`/users/{userId}`)、查询字符串 (`/users?role=admin`)、标头 (`X-CustomHeader: Value`) 或 cookie (`Cookie: debug=0`) 传递参数 ## 请求体-requestBody > [详细说明](https://swagger.io/docs/specification/describing-request-body/) ``` paths: /users: post: summary: Creates a user. requestBody: required: true content: application/json: schema: type: object properties: username: type: string responses: '201': description: Created ``` ## 响应 > [详细说明](https://swagger.io/docs/specification/describing-responses/) ``` paths: /users/{userId}: get: summary: Returns a user by ID. parameters: - name: userId in: path required: true description: The ID of the user to return. schema: type: integer format: int64 minimum: 1 responses: '200': description: A user object. content: application/json: schema: type: object properties: id: type: integer format: int64 example: 4 name: type: string example: Jessica Smith '400': description: The specified user ID is invalid (not a number). '404': description: A user with the specified ID was not found. default: description: Unexpected error ``` ## 输入和输出模型 > [详细说明](https://swagger.io/docs/specification/describing-responses/) 全局`components/schemas` 部分允许您定义 API 中使用的通用数据结构. 一个json 对象 ``` { "id": 4, "name": "Arthur Dent" } ``` 可以通过以下方式表示 ``` components: schemas: User: type: object properties: id: type: integer example: 4 name: type: string example: Arthur Dent # Both properties are required required: - id - name ``` 在请求体和相应体中表示 ``` paths: /users/{userId}: get: summary: Returns a user by ID. parameters: - in: path name: userId required: true schema: type: integer format: int64 minimum: 1 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/User' # <------- /users: post: summary: Creates a new user. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/User' # <------- responses: '201': description: Created ``` ## Authentication > [详细说明](https://swagger.io/docs/specification/authentication/) `securitySchemes`和`security`关键字用于描述 API 中使用的身份验证方法 ``` components: securitySchemes: BasicAuth: type: http scheme: basic security: - BasicAuth: [] ``` 支持的身份验证方法有： * HTTP 身份验证：[Basic](https://swagger.io/docs/specification/authentication/basic-authentication/)、[Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/)等。 * [API 密钥](https://swagger.io/docs/specification/authentication/api-keys/)作为标头或查询参数或在 cookie 中 * [认证 2](https://swagger.io/docs/specification/authentication/oauth2/) * [OpenID 连接发现](https://swagger.io/docs/specification/authentication/openid-connect-discovery/)