않도록 보일러 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' 

나는 또한 발생 비슷한 문제가 '내가 할 수있는 것입니다 enum 속성과 매개 변수를 제외합니다. 내 Swagger 코드가 더 건조해질 수 있습니까?

Answer 1

예, 코드가 훨씬 건조해질 수 있습니다. OpenAPI (fka. Swagger) 사양은 응답, 매개 변수 및 열거 형을 포함하여 여러 가지 요인을 제공합니다.

재사용 응답

당신은 당신이 당신의 예에 Error을 정의 거의 같은 방법으로 재사용 응답을 정의 할 수 있습니다.

는 우선,

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

이어서 루트 레벨 responses, 예 Standard404 위해 정의 응답을 추가

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

재사용 가능한 모든 조작에 responses에 $ref : '#/responses/Standard404' 404 상태 코드와 함께 사용 매개 변수

재사용 가능한 매개 변수 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.