openAPI.yml 분석

consumes, produces

consumes와 produces 섹션은 API에서 지원하는 MIME 유형을 정의.

 

definitions

전역 정의 섹션을 사용하면 API에서 사용되는 공통 데이터 구조를 정의 할 수 있습니다. 요청 본문과 응답 본문 모두에 대해 스키마가 필요할 때마다 $ ref를 통해 참조 할 수 있습니다. 예를 들어 다음 JSON 객체는 다음과 같습니다.

{
  "id": 4,
  "name": "Arthur Dent"
}
 
다음과 같이 나타낼 수 있습니다.
 
definitions:
  User:
    properties:
      id:
        type: integer
      name:
        type: string
    # Both properties are required
    required:  
      - id
      - name

 

paths

paths 섹션은 API의 개별 엔드 포인트(경로)와 이러한 엔드 포인트에서 지원하는 HTTP 메서드(작업)를 정의합니다. 예를 들어 POST /encrypted-data-vaults는 다음과 같이 설명 할 수 있습니다.

paths:
  /encrypted-data-vaults:
    post:
      operationId: createVaultReq
      parameters:
      - in: body
        name: NewVaultRequest
        schema:
          $ref: '#/definitions/DataVaultConfiguration'
      responses:
        "201":
          $ref: '#/responses/createVaultRes'
        default:
          $ref: '#/responses/genericError'
      summary: Creates a new data vault.

 

parameters

작업에는 URL 경로(/ users /{userId}), 쿼리 문자열 (/users?role=admin), 헤더 (X-CustomHeader: Value) 및 요청 본문을 통해 전달할 수있는 매개 변수가있을 수 있습니다. 매개 변수 유형, 형식, 필수 여부 및 기타 세부 사항을 정의할 수 있습니다.

/encrypted-data-vaults/{vaultID}/documents:
    get:
      operationId: readAllDocumentsReq
      parameters:
      - in: path
        name: vaultID
        required: true
        type: string
        x-go-name: VaultID
      responses:
        "201":
          $ref: '#/responses/readAllDocumentsRes'
        default:
          $ref: '#/responses/genericError'
      summary: Retrieves all encrypted documents from the specified vault.

 

responses 

각 작업에 대해 200 OK 또는 404 Not Found와 같은 가능한 상태 코드와 응답 본문의 스키마를 정의 할 수 있습니다. 스키마는 인라인으로 정의되거나 $ ref를 통해 외부 정의에서 참조 될 수 있습니다. 다양한 콘텐츠 유형에 대한 예제 응답을 제공할 수도 있습니다.

responses:
  createDocumentRes:
    description: createDocumentRes model
    headers:
      Location:
        type: string
  createVaultRes:
    description: createVaultRes model
    headers:
      Location:
        type: string
  emptyRes:
    description: emptyRes model
  genericError:
    description: genericError model
  getLogSpecRes:
    description: getLogSpecRes model
    headers:
      spec:
        type: string
  queryVaultRes:
    description: queryVaultRes model
  readAllDocumentsRes:
    description: readAllDocumentsRes model
  readDocumentRes:
    description: readDocumentRes model

 

 

 

 

출처: swagger.io/docs/specification/2-0/basic-structure/