Swagger(스웨거)

- 스웨거(Swagger)는 Open Api Specification(OAS)를 위한 Framework 입니다.

 

- API들이 가지고 있는 Spec을 명세, 관리할 수 있습니다. (API문서화)

 

- 협업을 해야 할 때 or 이미 만들어져 있는 프로젝트에 대해 유지보수를 진행할 때 등 구축되어 있는 API서버가 어떤 스펙을 가지고 있는지 쉽게 파악할 수 있도록 도와줍니다.

 

- 스웨거 공식 사이트 : https://swagger.io

 

 

저는 최근 VSCode의 Extension중 OpenAPI (Swagger) Editor를 이용하여 yaml 파일로 작업해보았는데요, Annotation을 통한 방법들도 있지만 yaml 파일에 작성하는 것이 비교적 깔끔한 방법이라고 생각합니다.

 

 

 

1. Version

 

openapi: 3.0.3 // version

 

 

 

2. Info

 

info:
  title: 'API Document Test' // API 이름
  description: 'API 문서 테스트' // API 설명
  
  // 추가적인 옵션
  version: 0.1.0-pre-release
  
  // information, license ... 

 

 

 

3. Servers

 

servers:
  - url: 'http://api.test.com/v1' // 서버 URL
    description: Optional server description ... // 설명

  // URL 여러개 등록 가능
  - url: 'http://api2.test.com/v1'
    description: Optional server description ...

 

 

4. Paths

 

paths:
  /users:	// path
    get:	// HTTP method
      summary: Returns a list of users.	// 기능 요약
      description: Optional extended description in CommonMark or HTML
      responses:	// 응답
        '200':
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

 

 

 

5. Parameters

 

paths:
  /users/{userId}:	// parameter
    get:
      summary: Returns a user by ID.
      parameters:
        - name: userId	// parameter 이름
          in: path	// parameter 위치
          required: true	// 필수 여부
          description: Parameter description in CommonMark or HTML.
         
          // 해당 스키마 정보
          // $ref : 중복되는 스키마 정보를 참조위치를 통해 삽입 가능. 
          // (ex. $ref: '#/components/schemas/User') paths section 하위에 사용
          schema:
            type : integer
            format: int64
            minimum: 1
      responses: 
        '200':
          description: OK

 

 

 

6. RequestBody

 

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

 

 

 

7. Response

 

paths:
  /users/{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