OpenAPI 명세

스캔 결과를 OpenAPI Specification 문서로 변환합니다. 생성된 스펙은 Swagger UI, Postman, Insomnia 등에 바로 임포트하여 API 문서화, 테스트, 목 서버 생성 등에 활용할 수 있습니다.

Noir는 OAS 2.0(Swagger)과 OAS 3.x를 모두 지원합니다.

사용법

OAS 3.0 (권장)

noir scan . -f oas3

OAS 2.0

noir scan . -f oas2

출력 예제

표준 OpenAPI 구조를 따릅니다. info에 메타데이터가, paths 아래에 각 URL 경로별 HTTP 메서드와 파라미터 정보가 들어갑니다. 이 결과를 Swagger Editor에 붙여넣으면 바로 시각화됩니다.

{
  "openapi": "3.0.3",
  "info": {
    "title": "Generated by Noir",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "http://localhost"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "x-api-key",
            "in": "header",
            "required": false,
            "schema": { "type": "string" }
          }
        ]
      }
    },
    "/query": {
      "post": {
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "my_auth",
            "in": "cookie",
            "required": false,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": { "type": "string" }
                }
              }
            }
          }
        }
      }
    }
  }
}

헤더, 쿠키, path, query 파라미터는 parameters로 나가고, form과 JSON 바디는 해당 미디어 타입의 requestBody가 됩니다. -f oas2는 Swagger 2.0 형태로 출력하며, 바디 파라미터는 in: formData / in: body 항목이 되고 쿠키는 Cookie 헤더로 실립니다.

문서는 OpenAPI 3.0.3으로 출력됩니다. 스캔 결과에 HTTP QUERY 라우트가 있으면 3.2.0으로 나가는데, 3.0.x에는 query 오퍼레이션이 없기 때문입니다.