OpenAPI 3.0 문서 작성 시 참조 정보

OpenAPI 3.0 스펙 사용

https://swagger.io/specification/

---

참고 사이트

• https://editor.swagger.io/ : 편집, 가져오기, 내보내기, 변환, 작성오류 추적 등 용이함
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md : 작성 샘플

작성 도구 - WebStrom 플러그인

• OpenAPI (Swagger) Editor

예시

openapi: 3.0.3
info:
  title: Project API
  description: Project API DOC
  contact:
    email: 1024corp@1024corp.com
  version: 0.0.1
servers:
  - url: <https://dev-api.com>
    description: 테스트 서버
  - url: 
    description: 로컬 서버
tags:
  - name: 회원(Member) API
paths:
  "/api/v1/member/{id}":
    put:
      tags:
        - 회원(Member) API
      summary: 회원 수정
      description: 회원 수정 API
      operationId: V1MemberUpdate
      parameters:
        - name: id
          in: path
          required: true
          example: 1
          description: 회원 식별자 정보
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_name:
                  type: string
                  example: ModifyName
                  description: 수정 이름 정보
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    example: 0.0.1
                    description: Version
                  timestamp:
                    type: number
                    example: 1672531200
                    description: Unix Timestamp
                  meta:
                    type: object
                    nullable: true
                    example: null
                    description: Meta
                  data:
                    type: object
                    nullable: true
                    example: null
                    description: Data
                required:
                  - version
                  - timestamp
                  - meta
                  - data
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: array
                    items:
                      type: object
                      properties:
                        statusCode:
                          type: number
                          example: 400
                        message:
                          type: string
                          example: user_name must be a string
                        error:
                          type: string
                          example: Bad Request
                required:
                  - message
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "409":
          description: Conflict
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: array
                    items:
                      type: string
                    example: [user_name cannot be modified.]
                required:
                  - message
      security:
        - AccessToken: []
components:
  schemas: {}
  securitySchemes:
    AccessToken:
      type: apiKey
      in: header
      name: access_token
      description: Enter your Access Token

1. 기본 정보
   • openapi : openAPI 버전 명시
   • info : api의 정보
2. 서버 정보
   • servers : 호스팅 서버 정보
3. 경로
   • paths : api 엔드포인트 경로, 각 경로에는 HTTP 메서드(GET, POST, PUT, DELETE 등)와 해당 경로의 요청/응답 형식을 정의하는 섹션을 포함한다
4. 주석
   • tags : api를 그룹화 하기 위한 태그 정의
   • summary, description : api에 대한 설명
5. 요청
   • parameters : 매개변수 정의
   • requestBody 요청 본문 형식 정의
6. 응답
   • response : 응답 형식 정의, 상태 코드와 응답 형식 지정, content 필드에 데이터 스키마 형식 지정
7. 보안 / 인증
   • security : api의 인증 방법 정의
   • securitySchemes : 사용되는 인증 체계 정의