OpenAPI 명세

OpenAPI 명세(OAS)는 RESTful API를 설명하기 위한 표준적이고 언어에 구애받지 않는 인터페이스입니다. 코드베이스에서 OAS 문서를 생성하면 대화형 API 문서를 쉽게 만들고, 자동화된 테스트를 설정하거나, API 정의를 다양한 다른 도구로 가져올 수 있습니다.

Noir는 OAS 2.0(이전의 Swagger) 및 OAS 3.0 명세를 모두 생성할 수 있습니다.

OpenAPI 명세 생성 방법

OAS 문서를 생성하려면 -f 또는 --format 플래그를 oas2 또는 oas3와 함께 사용하세요.

• OAS 3.0용 (권장):

  noir -b . -f oas3
  

• OAS 2.0용:

  noir -b . -f oas2
  

이렇게 하면 지정된 OpenAPI 버전을 준수하는 JSON 문서가 출력됩니다.

OAS 3.0 출력 예제

oas3 형식 출력의 샘플입니다:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Generated by Noir",
    "version": ""
  },
  "paths": {
    "/": {
      "get": {
        "responses": {
          "200": {
            "description": "Successful response"
          }
        },
        "parameters": [
          {
            "name": "x-api-key",
            "in": "header"
          }
        ]
      }
    },
    "/query": {
      "post": {
        "responses": {
          "200": {
            "description": "Successful response"
          }
        },
        "parameters": [
          {
            "name": "my_auth",
            "in": "query"
          },
          {
            "name": "query",
            "in": "formData"
          }
        ]
      }
    }
    // ... 다른 모든 엔드포인트에 대해서도 계속
  }
}

이 기능을 사용하면 소스 코드에서 직접 포괄적이고 정확한 API 명세를 자동으로 생성하여 시간을 절약하고 문서가 항상 최신 상태를 유지하도록 할 수 있습니다.