避免樣板2.0

Question

我的API尊重傳統的狀態代碼，我發現自己重複我的API定義的響應部分相同的文字

404: 
      description: The resource doesn't exist 
      schema: 
      $ref: '#/definitions/Error' 
default: 
      description: An unexpected error has occurred 
      schema: 
      $ref: '#/definitions/Error' 

類似的問題我也遇到的是，我可以」 t分解枚舉屬性和參數。我的Swagger代碼能變得更幹嗎？

Answer 1

是的，你的代碼可能變得更加乾燥：OpenAPI（fka。Swagger）規範提供了很多分解事物的方法，包括響應，參數和枚舉。

可重複使用的反應

您可以定義可重複使用的反應幾乎是你在你的例子定義Error以同樣的方式。

首先在responses上根級別添加響應，例如Standard404，定義

responses: 
    Standard404: 
    description: The resource doesn't exist 
    schema: 
     $ref: '#/definitions/Error' 

然後，在responses與$ref : '#/responses/Standard404'爲404個狀態碼使用它的任何操作

responses: 
    404: 
    $ref: '#/responses/Standard404' 

可重複使用的參數

對於可重複使用的參數rs，這是一回事。

首先在parameters上根級別添加參數，例如ID，定義：

parameters: 
    ID: 
    name: id 
    in: path 
    required: true 
    type: string 

在與$ref: '#/parameters/ID'參數的任何列表然後使用它。 臨提示：參數可以在操作層面上定義，而且在路徑級別：

/other-resources/{id}: 
    get: 
     parameters: 
     - $ref: '#/parameters/ID' 

/resources/{id}: 
    parameters: 
     - $ref: '#/parameters/ID' 

可重複使用的枚舉

所有你需要做的就是定義一個字符串類型的定義（或整數或數字）與枚舉：

SomeValueWithEnum: 
    type: string 
    enum: 
     - a value 
     - another value 

然後，你想這樣使用它很多次：

Resource: 
    properties: 
     dummyProperty: 
     $ref: '#/definitions/SomeValueWithEnum' 

完整的示例

下面是這3個用例完整的例子：

swagger: '2.0' 

info: 
    version: 1.0.0 
    title: API 
    description: Reusable things example 

paths: 

    /resources: 
    post: 
     responses: 
     200: 
      description: OK 
     default: 
      $ref: '#/responses/Default' 

    /resources/{id}: 
    parameters: 
     - $ref: '#/parameters/ID' 
    get: 
     responses: 
     200: 
      description: OK 
     404: 
      $ref: '#/responses/Standard404' 
     default: 
      $ref: '#/responses/Default' 
    delete: 
     responses: 
     200: 
      description: OK 
     404: 
      $ref: '#/responses/Standard404' 
     default: 
      $ref: '#/responses/Default' 

    /other-resources/{id}: 
    get: 
     parameters: 
     - $ref: '#/parameters/ID' 
     responses: 
     200: 
      description: OK 
     404: 
      $ref: '#/responses/Standard404' 
     default: 
      $ref: '#/responses/Default' 

definitions: 
    Error: 
    properties: 
     message: 
     type: string 

    SomeValueWithEnum: 
    type: string 
    enum: 
     - a value 
     - another value 

    Resource: 
    properties: 
     dummyProperty: 
     $ref: '#/definitions/SomeValueWithEnum' 

    AnotherResource: 
    properties: 
     anotherDummyProperty: 
     $ref: '#/definitions/SomeValueWithEnum' 

parameters: 
    ID: 
    name: id 
    in: path 
    required: true 
    type: string 

responses: 
    Standard404: 
    description: The resource doesn't exist 
    schema: 
     $ref: '#/definitions/Error' 
    Default: 
    description: An unexpected error has occurred 
    schema: 
     $ref: '#/definitions/Error' 

更多關於這 你應該閱讀這tutorial（披露：我寫的），並OpenAPI Specification。