定義全局參數

我正在準備我的API文檔，並且不是自動生成的。在那裏我有頭應該被髮送到所有的API，不知道是否有可能爲整個API定義全局參數？定義全局參數

這些標頭中的一些是靜態的，有些必須在調用API時進行設置，但它們在所有API中都是相同的，我不想複製和粘貼每個API和每種方法的參數，因爲這樣會將來不可維護。

我看到了API定義的靜態頭文件，但沒有單獨的文檔來說明如何有人可以設置它們或使用它們。

這是可能的嗎？

2013-10-25 mohamnag

按照this Swagger issue comment，全球參數（包括頭參數）的支持是不是在可預見的未來計劃，但限制你應該使用參數引用爲@Arnaud's答案（parameters: - $ref: '#/parameters/paramX'）重複。

來源

2015-12-07 12:35:14 botchniaque

如果你對調用API時受到消費者發送頭參數說話：

您至少可以在參數部分一勞永逸定義它們需要的時候則僅引用它們。在下面的例子：

CommonPathParameterHeader，ReusableParameterHeader和AnotherReusableParameterHeader在parameters定義一勞永逸對文檔的根，並且可以在任何參數列表
CommonPathParameterHeader在的/resourcesparameters部分中引用被用於和/other-resources路徑，這意味着這些路徑的所有操作都需要此標頭
ReusableParameterHeader在get /resources中被引用，這意味着它在此操作上需要

get /other-resources

舉例

同一件事：

swagger: '2.0' 
info: 
    version: 1.0.0 
    title: Header API 
    description: A simple API to learn how you can define headers 

parameters: 
    CommonPathParameterHeader: 
    name: COMMON-PARAMETER-HEADER 
    type: string 
    in: header 
    required: true 
    ReusableParameterHeader: 
    name: REUSABLE-PARAMETER-HEADER 
    type: string 
    in: header 
    required: true 
    AnotherReusableParameterHeader: 
    name: ANOTHER-REUSABLE-PARAMETER-HEADER 
    type: string 
    in: header 
    required: true 

paths: 
    /resources: 
    parameters: 
     - $ref: '#/parameters/CommonPathParameterHeader' 
    get: 
     parameters: 
     - $ref: '#/parameters/ReusableParameterHeader' 
     responses: 
     '200': 
      description: gets some resources 
    /other-resources: 
    parameters: 
     - $ref: '#/parameters/CommonPathParameterHeader' 
    get: 
     parameters: 
     - $ref: '#/parameters/AnotherReusableParameterHeader' 
     responses: 
     '200': 
      description: gets some other resources 
    post: 
     responses: 
     '204': 
      description: Succesfully created.

如果每個API響應 可惜你不能定義可重複使用的響應頭髮送您談頭。但至少您可以定義包含這些標頭的可重複使用的響應，例如500等常見響應。

實施例：

swagger: '2.0' 
info: 
    version: 1.0.0 
    title: Header API 
    description: A simple API to learn how you can define headers 

parameters: 
    CommonPathParameterHeader: 
    name: COMMON-PARAMETER-HEADER 
    type: string 
    in: header 
    required: true 
    ReusableParameterHeader: 
    name: REUSABLE-PARAMETER-HEADER 
    type: string 
    in: header 
    required: true 
    AnotherReusableParameterHeader: 
    name: ANOTHER-REUSABLE-PARAMETER-HEADER 
    type: string 
    in: header 
    required: true 

paths: 
    /resources: 
    parameters: 
     - $ref: '#/parameters/CommonPathParameterHeader' 
    get: 
     parameters: 
     - $ref: '#/parameters/ReusableParameterHeader' 
     responses: 
     '200': 
      description: gets some resources 
      headers: 
      X-Rate-Limit-Remaining: 
       type: integer 
      X-Rate-Limit-Reset: 
       type: string 
       format: date-time 
    /other-resources: 
    parameters: 
     - $ref: '#/parameters/CommonPathParameterHeader' 
    get: 
     parameters: 
     - $ref: '#/parameters/AnotherReusableParameterHeader' 
     responses: 
     '200': 
      description: gets some other resources 
      headers: 
      X-Rate-Limit-Remaining: 
       type: integer 
      X-Rate-Limit-Reset: 
       type: string 
       format: date-time 
    post: 
     responses: 
     '204': 
      description: Succesfully created. 
      headers: 
      X-Rate-Limit-Remaining: 
       type: integer 
      X-Rate-Limit-Reset: 
       type: string 
       format: date-time 
     '500': 
      $ref: '#/responses/Standard500ErrorResponse' 

responses: 
    Standard500ErrorResponse: 
    description: An unexpected error occured. 
    headers: 
     X-Rate-Limit-Remaining: 
     type: integer 
     X-Rate-Limit-Reset: 
     type: string 
     format: date-time

關於所述OpenAPI（FKA揚鞭。）接着版本

的OpenAPI的規格（FKA揚鞭。）將演變和包括除其他事項外可重複使用的響應報頭的定義（參見https://github.com/OAI/OpenAPI-Specification/issues/563）。

來源

2016-05-16 12:50:02

定義全局參數

回答

相關問題