定义全局参数

我正在准备我的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

定义全局参数

回答

相关问题