Swagger从入门到放弃
如何編寫基于OpenAPI規范的API文檔
簡介
Swagger
Swagger是一個簡單但功能強大的API表達工具。支持的語言種類繁多
使用Swagger生成API，我們可以得到交互式文檔，自動生成代碼的SDK以及API的發現特性
OpenAPI規范
OpenAPI規范是Linux基金會的一個項目，試圖定義一種用來描述API格式或API定義的語言，來規范RESTful服務的開發過程
OpenAPI可以幫助我們描述一個API的基本信息：
有關API的一般性描述
可用路徑
在每個路徑上的可用操作
每個操作的輸入輸出格式
OpenAPI規范這類API定義語言能夠更簡單、快速的表述API，尤其是在API設計階段作用比較明顯
如何編寫API文檔
編輯器采用在線編輯：https://editor.swagger.io/
swagger: "2.0"
info:
description:
version: "1.0.0"
title: "Swagger Petstore"
termsOfService: "http://swagger.io/terms/"
contact:
email: "apiteam@swagger.io"
license:
name: "Apache 2.0"
url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"
tags:
- name: "pet"
description: "Everything about your Pets"
externalDocs:
description: "Find out more"
url: "http://swagger.io"
- name: "store"
description: "Access to Petstore orders"
- name: "user"
description: "Operations about user"
externalDocs:
description: "Find out more about our store"
url: "http://swagger.io"
schemes:
- "http"
paths:
/pet:
post:
tags:
- "pet"
summary: "Add a new pet to the store"
description: ""
operationId: "addPet"
consumes:
- "application/json"
- "application/xml"
produces:
- "application/xml"
- "application/json"
parameters:
- in: "body"
name: "body"
description: "Pet object that needs to be added to the store"
required: true
schema:
$ref: "#/definitions/Pet"
responses:
405:
description: "Invalid input"
security:
- petstore_auth:
- "write:pets"
- "read:pets"
從零開始
swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
{}
顯示界面如下：
首先要通過swagger屬性來聲明OpenAPI規范的版本
然后需要說明API文檔的相關信息，比如API文檔版本、API文檔名稱、描述信息等
最后作為webURL，一個很重要的信息就是用來給消費者使用的 根URL ，可以使用協議http或https、主機名、根路徑來描述：
schemes:
- https
host: simple.api
basePath: /openapi101
```
接下來就是寫API的操作，通過paths，然而這里沒有寫只是通過{}對象占用位置
swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
get:
summary: Get some persons
description: Returns a list containing all persons
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstname:
type: string
lastname:
type: string
username:
type: string
在上面的這些代碼中，做了以下的動作：
添加了/persons的路徑，用來訪問一組用戶信息
在路徑中添加了HTTP方法get，同時也有一些簡單的描述信息summary和description
定義響應類型responses，響應類型中添加了HTTP狀態碼200
定義了響應內容：通過響應消息中的schema屬性來描述清楚具體的返回內容。通過type屬性可知一組用戶信息就是一個用戶信息數組，每一個數組元素則是一個用戶對象，該對象包含三個string類型的屬性，其中username必須提供（required）
定義請求參數
paths:
/persons:
get:
summary: Get some persons
description: Returns a list containing all persons
parameters:
- name: pageSize
in: query
description: Number of persons returned
type: integer
- name: pageNumber
in: query
description: Page number
type: integer
首先在get方法中添加了一個parameters屬性
在參數列表中，添加了兩個參數pageSize和pageNumber的整形參數，并有簡單描述
定義路徑參數
swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons/{username}:
get:
summary: Get some persons
description: Returns a list containing all persons
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
responses:
200:
description: A list of Person
schema:
type: array
items:
required:
- username
properties:
firstname:
type: string
lastname:
type: string
username:
type: string
路徑參數、請求參數以及消息參數等的不同之處就在于in屬性的值不同，分別為path、query、body等。同時對于參數的類型可以使用type或者schema來定義，例如消息體參數如下：
swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
post:
summary: Creates a person
description: Adds a new person to the persons list
parameters:
- name: person
in: body
description: The person to create
schema:
required:
- username
properties:
firstname:
type: string
lastname:
type: string
username:
type: string
responses:
200:
description: OK
如果是單個參數可以使用type進行定義例如integer，string ，array等，而如果是json類型的參數就需要使用schema類來定義。
定義相應消息
response:
204:
description:Persons successfully created
400:
description:Persons couldn't have been created
簡化數據模型
通過使用definition來定義可重用的對象。如下：
swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
post:
summary: Creates a person
description: Adds a new person to the persons list
parameters:
- name: person
in: body
description: The person to create
schema:
$ref: '#/definitions/Person'
responses:
200:
description: OK
schema:
$ref: "#/definitions/Person"
definitions:
Person:
required:
- username
properties:
firstname:
type: string
lastname:
type: string
username:
type: string
定義可重用的參數
swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation
schemes:
- https
host: simple.api
basePath: /openapi101
paths:
/persons/{username}:
get:
parameters:
- $ref: '#/parameters/username'
responses:
200:
description: fsafsf
parameters:
username:
name: username
in: path
required: true
description: The person's username
type: string
高級定義
字符串的長度和格式
- name: username
in: path
required: true
description: fasfsa
type: string
pattern: "[a-z0-9]{8,64}"
minLength: 8
maxLength: 64
日期和時間
parameters:
- name: dateofBirth
in: query
description: fasfsaf
type: string
format: date
枚舉類型
code:
type: string
enum:
- DBERR
- NTERR
- UNERR
高級參數
參數的媒體類型
在文檔的根節點下面添加：
produces:
- text/xml
consumes:
- application/json
- application/xml
高級響應消息
要定義一個不帶消息體的相應消息，只需要寫響應狀態和描述即可
responses:
'204':
description: Person successfully created
與請求消息類似，必帶參數使用required來標識
Person:
required:
- username
properties:
firstname:
type: string
lastname:
type: string
username:
type: string
分類標簽
tags: - Persons
總結
以上是生活随笔為你收集整理的Swagger从入门到放弃的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 求数字序列中的第n位对应的数字
- 下一篇： Auth模块