TIL > API 문서 작성하기 (swagger)

제가 공부한 것을 단순히 기록(보여주기)하기 위해 작성하였습니다!!!!!!!!!

아래의 요구사항에 대해서 Swagger 의 yaml 형식으로 OpenAPI 명세서를 작성하였습니다.

- 조회
	블로그 글 전체 조회
	특정 블로그 글 조회
	모든 댓글 조회
	특정 댓글 조회
- 생성
	새 블로그 글 생성
	새 댓글 생성
- 삭제
	특정 블로그 글 삭제
	특정 댓글 삭제
- 수정
	특정 블로그 글 수정
	특정 댓글 수정

 

작성한 git 레포지토리: https://github.com/SangYunLeee/sprint-open-api-doc/blob/main/openapi.yaml

 

데이터 모델링과 url-path, statusCode등을 포함하여 작성하였습니다.

스웨거 작성 결과:

이하 작성한  Swagger YAML 입니다.

openapi: 3.0.0
info:
  description: '블로그 API 문서입니다.'
  version: '1.0.0'
  title: '블로그 API'
components:
  schemas:
    User:
      type: object
      required:
        - id
        - loginId
        - name
        - password
      properties:
        id:
          type: integer
          format: int64
          example: 523452
        loginId:
          type: string
          example: sororiri
        password:
          type: string
          example: dfaf3q!
        name:
          type: string
          example: 피리
    Article:
      type: object
      required:
        - title
        - body
        - authorId
      properties:
        id:
          type: integer
          format: int64
          example: 2
        title:
          type: string
          example: '3월 15일의 TIL'
        body:
          type: string
          example: '오늘은 REST API를 배웠다!'
        author:
          $ref: '#/components/schemas/User'
    Comment:
      type: object
      required:
        - author
        - body
        - articleId
      properties:
        id:
          type: integer
          format: int64
          example: 1
        author:
          $ref: '#/components/schemas/User'
        body:
          type: string
          example: '열심히 공부하셨군요. 잘 보고 갑니다.'
        articleId:
          type: integer
          format: int64
          example: 2
paths:
  /article:
    get:
      tags:
        - article
      description: '블로그 글 전체 조회'
      responses:
        '200':
          description: '성공 응답'
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Article'
    post:
      tags:
        - article
      description: '새 블로그 글 작성'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Article'
      responses:
        '200':
          description: '글 등록 완료'
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    $ref: '#/components/schemas/Article'
  /article/{articleId}:
    get:
      tags:
        - article
      description: 'id에 대응되는 블로그 글 조회'
      parameters:
        - name: articleId
          in: path
          description: 조회할 블로그의 ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: '글 조회 성공'
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    $ref: '#/components/schemas/Article'
    put:
      tags:
        - article
      description: id 를 통한 기존 블로그 글 수정
      parameters:
        - name: articleId
          in: path
          description: 변경할 블로그의 ID
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Article'
      responses:
        '200':
          description: 글 수정 완료
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
    delete:
      tags:
        - article
      description: id 를 통한 기존 블로그 글 삭제
      parameters:
        - name: articleId
          in: path
          description: 삭제할 블로그의 ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 블로그 삭제 성공
  /comments:
    get:
      tags:
        - comment
      description: '댓글 전체 조회'
      responses:
        '200':
          description: '성공 응답'
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Comment'
    post:
      tags:
        - comment
      description: '댓글 작성'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Comment'
      responses:
        '200':
          description: '댓글 등록 완료'
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    $ref: '#/components/schemas/Comment'
  /comments/{commentId}:
    get:
      tags:
        - comment
      description: 'id에 대응되는 댓글 조회'
      parameters:
        - name: commentId
          in: path
          description: 조회할 댓글의 ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: '댓글 조회 성공'
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    $ref: '#/components/schemas/Comment'
    put:
      tags:
        - comment
      description: 댓글 수정
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Comment'
      parameters:
        - name: commentId
          in: path
          description: 변경할 댓글의 ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 댓글 수정 완료
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    $ref: '#/components/schemas/Comment'
    delete:
      tags:
        - comment
      description: id 를 통한 기존 댓글 삭제
      parameters:
        - name: commentId
          in: path
          description: 삭제할 댓글의 ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 댓글 삭제 성공

servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/cs-kimcoding/blog/1.0.0