Definire i parametri globali

Question

Sto preparando la documentazione API eseguendola manualmente e non generata automaticamente. Ci sono intestazioni che devono essere inviate a tutte le API e non so se è possibile definire i parametri globalmente per l'intera API o no?

alcune di queste intestazioni sono statiche e alcune devono essere impostate quando viene effettuata la chiamata all'API, ma sono tutte uguali in tutte le API, non voglio copiare e incollare i parametri per ogni API e ogni metodo in quanto questo non essere mantenibile in futuro.

Ho visto le intestazioni statiche con la definizione dell'API ma non esiste un singolo documento per come qualcuno può impostarle o usarle.

è possibile o no?

Answer 1

Come da this Swagger issue comment, il supporto per i parametri globali (compresi i parametri di intestazione) non è prevista nel prossimo futuro, ma per limitare la ripetizione è necessario utilizzare parametri riferimenti come in @Arnaud's risposta (parameters: - $ref: '#/parameters/paramX').

Answer 2

Se il vostro parlando di parametri di intestazione inviati dal consumatore al momento della chiamata l'API:

Si può almeno definire una volta per tutte in sezioni parametri quindi fare riferimento solo quando necessario. Nell'esempio sottostante:

• CommonPathParameterHeader, ReusableParameterHeader e AnotherReusableParameterHeader sono definiti una volta per tutte in parameters sulla radice del documento e può essere utilizzato in qualsiasi elenco parametri
• CommonPathParameterHeader è indicizzato nei parameters sezione /resources e /other-resources percorsi, il che significa che tutte le operazioni di questi percorsi bisogno di questo colpo di testa
• ReusableParameterHeader è indicizzato nei get /resources senso che è necessario in questa operazione
01.235.164,106 mila
• Stessa cosa per AnotherReusableParameterHeader in get /other-resources

Esempio:

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. 

Se il vostro parlare di intestazione inviato con ogni risposta API Purtroppo non si può definisce intestazioni di risposta riutilizzabili. Ma almeno è possibile definire una risposta riutilizzabile contenente queste intestazioni per una risposta comune come ad esempio 500.

Esempio:

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 

Chi OpenAPI (fka Swagger.) Versione successiva

Le specifiche OpenAPI (fka Swagger.) Si evolverà e comprendono la definizione di intestazioni di risposta riutilizzabili tra le altre cose (Cfr. https://github.com/OAI/OpenAPI-Specification/issues/563).