[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/)