OAS 3.0

Posted on | Edited on | In | Comments:

document 문서

git : https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md
swagger : https://swagger.io/docs/specification/basic-structure/

meta data, server 정보

1
2
3
4
5
6
7
8
9
10
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

data type

기본 타입

https://swagger.io/docs/specification/data-models/data-types/

  • string, number, integer, boolean, array, object 사용가능
  • string 은 date와 file을 포함함
  • array는 items가 필수로 와야함. items 아래 type 혹은 $ref

api 정의

path 정의

paths 아래에 정의한다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
paths:
  /users:
    get:
        operationId: getUsers
        summary: get user
        description: get user description
    post:
        operationId: createUser
        summary: create user
        description: create given user
  /users/{id}:
    get:
        ...
    patch:
        deprecated: true
  • path 아래 http method 별로 선언 가능
  • summary랑 description 차이가 뭐지?
  • operationId는 나중에 code-gen 에서 메서드명으로 사용됨
  • path templating 할 수 있고, 파라미터에서 받을 수 있음
  • deprecated 할 수 있음

parameter 정의

https://swagger.io/docs/specification/describing-parameters/
기본 형태는 아래와 같음

1
2
3
4
5
6
7
8
9
10
11
paths:
  /users/{id}:
    get:
      parameters:
        - in: path
          name: id  # 상단의 path명과 같아야함
          required: true
          schema:
            type: integer
            minimum: 1
          description: The user ID
  • 파라미터 형태, 이름, 필수여부 등을 줄 수 있음. 추가적인 정보는 여기 확인
    • in에는 path, query, header, cookie 가 올 수 있음
    • path의 경우 url에 path templating과 이름을 동일하게 해줘야 한다는 점 빼고는 모두 동일하게 사용 가능
  • schema에서 전달받은 파라미터에 대해 정의함. 타입, 최소값 등을 줄 수 있음. 추가적인 정보는 여기 확인

request body

https://swagger.io/docs/specification/describing-request-body/

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
paths:
    /pets:
        post:
            summary: Add a new pet
            requestBody:
            description: Optional description in *Markdown*
            required: true
            content:
                application/json:
                schema:
                    $ref: '#/components/schemas/Pet'
    /pets:
        post:
            summary: Add a new pet
            requestBody:
                description: Optional description in *Markdown*
                required: true
                content:
                application/json:
                    schema:
                        type: object
                        properties:

object 정의

https://swagger.io/docs/specification/components/
components 아래에 정의하고, 재사용을 목적으로 한다.
$ref 속성을 이용하고 #으로 참조한다.

1
$ref: '#/components/schemas/Item'

#는 현 위치를 말한다.

schemas

일반 오브젝트(DTO 등)

parameters

https://swagger.io/docs/specification/describing-parameters/#common-for-various-paths

Common Parameters for Various Paths 부분 참조

responses

https://swagger.io/docs/specification/describing-responses/

status 별로 선언가능하며 description, object 등을 내려줄 수 있다

enum reuse

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
paths:
  /products:
    get:
      parameters:
      - in: query
        name: color
        required: true
        schema:
          $ref: '#/components/schemas/Color'
      responses:
        '200':
          description: OK
          
components:
  schemas:
    Color:
      type: string
      enum:
        - black
        - white
        - red
        - green
        - blue