[Swagger] Basic Structure (OpenAPI 3)

Link 를 번역했습니다. (2020-10-25)

Basic Structure

YAML 또는 JSON으로 OpenAPI 정의(definition)를 작성할 수 있습니다. 이 가이드에서는 YAML 예제만 사용하지만 JSON은 똑같이 잘 작동합니다. YAML로 작성된 샘플 OpenAPI 3.0 정의는 다음과 같습니다.

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

모든 키워드 이름은 대소 문자를 구분합니다.

Metadata

모든 API 정의에는 이 정의의 기반이 되는 OpenAPI 사양(specification)의 버전이 포함되어야 합니다.

openapi: 3.0.0

OpenAPI 버전은 API 정의의 전체 구조, 즉 문서화 할 수 있는 내용과 문서화 방법을 정의합니다. OpenAPI 3.0은 three-part 버전 번호로 시맨틱 버전 관리(semantic versioning)를 사용합니다. 사용 가능한 버전은 3.0.0, 3.0.1, 3.0.2 및 3.0.3입니다. 기능적으로 동일합니다.

info 섹션에는 API 정보가 포함됩니다: title, description(optional), version

info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9

title은 API 이름입니다. description은 API에 대한 확장 정보입니다. 여러 줄로 구성 될 수 있으며 서식있는 텍스트 표현을 위해 Markdown의 CommonMark 언어를 지원합니다. HTML은 CommonMark에서 제공하는 범위까지 지원됩니다 (CommonMark 0.27 사양의 HTML 블록 참조). version은 API의 버전을 지정하는 임의의 문자열입니다 (파일 개정 또는 openapi 버전과 혼동하지 마십시오). major.minor.patch와 같은 시맨틱 버전 관리를 사용하거나 1.0-beta 또는 2017-07-25 와 같은 임의의 문자열을 사용할 수 있습니다. info는 또한 연락처 정보, 라이센스, 서비스 약관 및 기타 세부 사항에 대한 기타 키워드를 지원합니다.

Servers

server 섹션은 API 서버 및 기본 URL을 지정합니다. 프로덕션 및 샌드 박스와 같은 하나 또는 여러 서버를 정의 할 수 있습니다.

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

모든 API 경로는 서버 URL에 상대적입니다. 위의 예에서 /users는 사용되는 서버에 따라 http://api.example.com/v1/users 또는 http://staging-api.example.com/users를 의미합니다. 자세한 내용은 API Server and Base Path 페이지를 참조하십시오.

Paths

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

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

작업(HTTP 메서드) 정의에는 parameter, request body(있는 경우), 가능한 response status code(예: 200 OK 또는 404 Not Found) 및 응답 내용이 포함됩니다. 자세한 내용은 Paths and Operations 페이지를 참조하십시오.

Parameters

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

paths:
  /user/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - name: userId
          in: path
          required: true
          description: Parameter description in CommonMark or HTML.
          schema:
            type : integer
            format: int64
            minimum: 1
      responses: 
        '200':
          description: OK

더 많은 정보는 Describing Parameters를 참고하세요.

Request Body

작업에서 요청 본문을 보내는 경우 requestBody 키워드를 사용하여 본문 콘텐츠 및 미디어 유형을 설명합니다.

paths:
  /users:
    post:
      summary: Creates a user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
      responses: 
        '201':
          description: Created

더 많은 정보는, Describing Request Body를 참고하세요.

Responses

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

paths:
  /user/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - name: userId
          in: path
          required: true
          description: The ID of the user to return.
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        '200':
          description: A user object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                    example: 4
                  name:
                    type: string
                    example: Jessica Smith
        '400':
          description: The specified user ID is invalid (not a number).
        '404':
          description: A user with the specified ID was not found.
        default:
          description: Unexpected error

응답 HTTP 상태 코드는 따옴표 "200"으로 묶어야합니다 (OpenAPI 2.0에서는 이를 필요로하지 않음). 자세한 내용은 Describing Responses을 참고하세요.

Input and Output Models

전역 components/schemas 섹션을 사용하면 API에서 사용되는 공통 데이터 구조를 정의 할 수 있습니다. 매개 변수, 요청 본문 및 응답 본문에서 schema가 필요할 때마다 $ref를 통해 참조할 수 있습니다. 예를 들어 다음 JSON 객체는 다음과 같습니다.

{
  "id": 4,
  "name": "Arthur Dent"
}

다음과 같이 나타낼 수 있습니다.

components:
  schemas:
    User:
      properties:
        id:
          type: integer
        name:
          type: string
      # Both properties are required
      required:  
        - id
        - name

그런 다음 요청 본문 스키마 및 응답 본문 스키마에서 다음과 같이 참조됩니다.

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - in: path
          name: userId
          required: true
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users:
    post:
      summary: Creates a new user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: Created

Authentication

securitySchemes 및 security 키워드는 API에서 사용되는 인증 방법을 설명하는 데 사용됩니다.

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
security:
  - BasicAuth: []

지원되는 인증 방법은 다음과 같습니다.

• HTTP 인증: Basic, Bearer 등
• API key as a header or query parameter or in cookies
• OAuth 2
• OpenID Connect Discovery

더 많은 정보는, Authentication를 참고하세요.

Full Specification

전체 OpenAPI 3.0 사양은 GitHub에 있습니다.