Swagger - HackMD

# Swagger > 一系列的 open-source 工具用來建立 OpenAPI 規格包含設計、建立、寫文件等等 - [範例](https://editor.swagger.io/?_ga=2.153179131.213900886.1632707085-1310170969.1632104466) - [DOC](https://swagger.io/docs/specification/about/) # 工具 - [Swagger Editor](https://editor.swagger.io/?_ga=2.185586413.577658464.1632832418-1310170969.1632104466) - 編輯 openAPI 規格 - [Swagger UI](https://swagger.io/tools/swagger-ui/) - 顯示 openAPI 規格的互動式API文件 - [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) - 建立 server studs 和 client libraries # 結構 - swagger - info - description - version - title - termsOfService - contact - email - license - name - url - host - basePath - tags - name - description - externalDocs - description - url - schemes - paths - url - http method - tags - summary - description - operationId - consumes - produces - parameters - in - name - description - required - schema - responses - http status code - description - security - auth name - action - securityDefinitions - auth name - type - authorizationUrl - flow - scopes - action - definitions - model name - type - properties - property name - type - format - enum - items(type = array) - default - xml - name # 語法 ## Metadata - openapi: 3.0.0 // OpenAPI version - info: - title: API 名稱 - description: 更多API的描述 - version: API 版本 ex: 1.0-beta or 2017-07-25 ## Servers 網址 ``` https://api.example.com/v1/users?role=admin&status=active \________________________/\____/ \______________________/ server URL endpoint query parameters path ``` - server url format - scheme://host[:port][/path] - servers: - url: API server 的網址 - description: 這台機器的描述像是 staging, production.. ### Server Templating > 當多個 server 網址中有一些部分是不一樣的時候 ```yaml= servers: - url: https://{customerId}.saas-app.com:{port}/v2 variables: customerId: default: demo description: Customer ID assigned by the service provider port: enum: - '443' - '8443' default: '443' ``` ## Paths - 獨立的一個 endpoints ```yaml= 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 ``` ### Path Templating ```yaml= /users/{id} /organizations/{orgId}/members/{memberId} /report.{format} ``` ### Operations - get - post - put - patch - delete - head - options - trace ### operationId > 選擇性的 unique string 用來辨識 operation ### Deprecated Operations 這個 url 不會再用了 ```yaml= /pet/findByTags: get: deprecated: true ``` ## Parameters ### path ```yaml= /users/{id} paths: /users/{id}: get: parameters: - in: path name: id # Note the name is the same as in the path required: true schema: type: integer minimum: 1 description: The user ID ``` ### query string ```yaml= /users?role=admin parameters: - in: query name: offset schema: type: integer description: The number of items to skip before starting to collect the result set - in: query name: limit schema: type: integer description: The numbers of items to return ``` ### headers ```yaml= X-MyHeader: Value paths: /ping: get: summary: Checks if the server is alive parameters: - in: header name: X-Request-ID schema: type: string format: uuid required: true ``` ### cookie ```yaml= Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCU parameters: - in: cookie name: debug schema: type: integer enum: [0, 1] default: 0 - in: cookie name: csrftoken schema: type: string ``` ### Required and Optional Parameters > Required 代表這個參數是否一定要帶 ### Default Parameter Values ```yaml= schema: type: integer minimum: 1 maximum: 100 default: 20 ``` ### Enum Parameters ```yaml= schema: type: string enum: - available - pending - sold ``` ### Constant Parameters ```yaml= schema: type: string enum: - now ``` ### Empty-Valued Parameters ```yaml= parameters: - in: query name: metadata schema: type: boolean allowEmptyValue: true # ``` ### Nullable Parameters ```yaml= schema: type: integer format: int32 nullable: true ``` ### Parameter Examples ```yaml= parameters: - in: query name: ids description: One or more IDs required: true schema: type: array items: type: integer style: form explode: false examples: oneId: summary: Example of a single ID value: [5] # ?ids=5 multipleIds: summary: Example of multiple IDs value: [1, 5, 7] # ?ids=1,5,7 ``` ### Deprecated Parameters ```yaml= - in: query name: format required: true schema: type: string enum: [json, xml, yaml] deprecated: true description: Deprecated, use the appropriate `Accept` header instead. ``` ### Common Parameters ```yaml= paths: /user/{id}: parameters: - in: path name: id schema: type: integer required: true description: The user ID get: summary: Gets a user by ID ... patch: summary: Updates an existing user with the specified ID ... delete: summary: Deletes the user with the specified ID ... ``` ### Common Parameters for Various Paths ```yaml= components: parameters: offsetParam: # <-- Arbitrary name for the definition that will be used to refer to it. # Not necessarily the same as the parameter name. in: query name: offset required: false schema: type: integer minimum: 0 description: The number of items to skip before starting to collect the result set. limitParam: in: query name: limit required: false schema: type: integer minimum: 1 maximum: 50 default: 20 description: The numbers of items to return. paths: /users: get: summary: Gets a list of users. parameters: - $ref: '#/components/parameters/offsetParam' - $ref: '#/components/parameters/limitParam' responses: '200': description: OK /teams: get: summary: Gets a list of teams. parameters: - $ref: '#/components/parameters/offsetParam' - $ref: '#/components/parameters/limitParam' responses: '200': description: OK ``` ## Request Body ```yaml= paths: /pets: post: summary: Add a new pet requestBody: description: Optional description in *Markdown* required: true content: application/json: schema: $ref: '#/components/schemas/Pet' application/xml: schema: $ref: '#/components/schemas/Pet' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PetForm' text/plain: schema: type: string responses: '201': description: Created ``` ## Responses ```yaml= paths: /users: get: summary: Get all users responses: '200': description: A list of users content: application/json: schema: $ref: '#/components/schemas/ArrayOfUsers' application/xml: schema: $ref: '#/components/schemas/ArrayOfUsers' text/plain: schema: type: string # This operation returns image /logo: get: summary: Get the logo image responses: '200': description: Logo image in PNG format content: image/png: schema: type: string format: binary ``` ### HTTP Status Codes ```yaml= responses: '200': description: OK '400': description: Bad request. User ID must be an integer and larger than 0. '401': description: Authorization information is missing or invalid. '404': description: A user with the specified ID was not found. '5XX': description: Unexpected error. ``` ### Response Body ```yaml= responses: '200': description: A User object content: application/json: schema: type: object properties: id: type: integer description: The user ID. username: type: string description: The user name. ``` ### Response That Returns a File ```yaml= paths: /report: get: summary: Returns the report in the PDF format responses: '200': description: A PDF file content: application/pdf: schema: type: string format: binary ``` ### Response Headers ```yaml= HTTP 1/1 200 OK X-RateLimit-Limit: 100 X-RateLimit-Remaining: 99 X-RateLimit-Reset: 2016-10-12T11:00:00Z ``` ### Default Response ```yaml= responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/User' # These two error responses have the same schema '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error ``` ### Reusing Responses ```yaml= paths: /users: get: summary: Gets a list of users. response: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ArrayOfUsers' '401': $ref: '#/components/responses/Unauthorized' # <----- /users/{id}: get: summary: Gets a user by ID. response: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/User' '401': $ref: '#/components/responses/Unauthorized' # <----- '404': $ref: '#/components/responses/NotFound' # <----- # Descriptions of common components components: responses: NotFound: description: The specified resource was not found content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' schemas: # Schema for error response body Error: type: object properties: code: type: string message: type: string required: - code - message ``` ## Media Types > request 或 response 的資料格式類型範例 ```yaml= application/json application/xml application/x-www-form-urlencoded multipart/form-data text/plain; charset=utf-8 text/html application/pdf image/png application/vnd.mycompany.myapp.v2+json application/vnd.ms-excel application/vnd.openstreetmap.data+xml application/vnd.github-issue.text+json application/vnd.github.v3.diff image/vnd.djvu ``` ### 多個 media type ```yaml= paths: /employees: get: summary: Returns a list of employees. responses: '200': # Response description: OK content: # Response body application/json: # One of media types schema: type: object properties: id: type: integer name: type: string fullTime: type: boolean application/xml: # Another media types schema: type: object properties: id: type: integer name: type: string fullTime: type: boolean ``` ## Input and Output Models > `components/schemas` 定義常見的資料格式範例 ```yaml= components: schemas: User: properties: id: type: integer name: type: string # Both properties are required required: - id - name ``` 使用 ```yaml= schema: $ref: '#/components/schemas/User' ``` ## Authentication > `securitySchemes` 和 `security ` 描述驗證的方法範例 ```yaml= components: securitySchemes: BasicAuth: type: http scheme: basic BearerAuth: type: http scheme: bearer security: - BasicAuth: [] ``` 使用 ```yaml= /pet/{petId}: delete: security: - petstore_auth: - "write:pets" - "read:pets" ``` ## Data Models (Schemas) [Data Models](https://swagger.io/docs/specification/data-models/) ## Adding Examples ```yaml= // 單一 parameters: - in: query name: status schema: type: string enum: [approved, pending, closed, new] example: approved # Example of a parameter value // 多個 parameters: - in: query name: limit schema: type: integer maximum: 50 examples: # Multiple examples zero: # Distinct name value: 0 # Example value summary: A sample limit value # Optional description max: # Distinct name value: 50 # Example value summary: A sample limit value # Optional description ``` ### Request and Response Body Examples ```yaml= paths: /users: post: summary: Adds a new user requestBody: content: application/json: schema: # Request body contents type: object properties: id: type: integer name: type: string example: # Sample object id: 10 name: Jessica Smith responses: '200': description: OK ``` ### Object and Property Examples ```yaml= // property-levle components: schemas: User: # Schema name type: object properties: id: type: integer format: int64 example: 1 # Property example name: type: string example: New order # Property example // object-level components: schemas: User: # Schema name type: object properties: id: type: integer name: type: string example: # Object-level example id: 1 name: Jessica Smith ``` ### Array Example ```yaml= omponents: schemas: ArrayOfInt: type: array items: type: integer format: int64 example: 1 components: schemas: ArrayOfInt: type: array items: type: integer format: int64 example: [1, 2, 3] components: schemas: ArrayOfUsers: type: array items: type: object properties: id: type: integer name: type: string example: - id: 10 name: Jessica Smith - id: 20 name: Ron Stewart ``` ## Using $ref ```yaml= components: schemas: User: properties: id: type: integer name: type: string ``` ## Grouping Operations With Tags ```yaml= paths: /pet/findByStatus: get: summary: Finds pets by Status tags: - pets ... /pet: post: summary: Adds a new pet to the store tags: - pets ... /store/inventory: get: summary: Returns pet inventories tags: - store ... ``` # 範例 - [openapi 2.0 可以用 edit 轉成 3.0](https://editor.swagger.io/?_ga=2.153179131.213900886.1632707085-1310170969.1632104466) ###### tags: `2021` `api` `design` `swagger` `api doc` {%hackmd BJrTq20hE %}

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.