OpenAPI Specification

Convert scan results into an OpenAPI Specification document. The generated spec can be imported into Swagger UI, Postman, Insomnia, and similar tools for API documentation, testing, or mock generation.

Noir supports both OAS 2.0 (Swagger) and OAS 3.x.

Usage

OAS 3.0 (recommended):

noir scan . -f oas3

OAS 2.0:

noir scan . -f oas2

Example Output

Follows the standard OpenAPI structure: info holds metadata, and paths maps each URL to its HTTP methods with parameters and responses. Paste the output into the Swagger Editor to visualize it right away.

{
  "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" }
                }
              }
            }
          }
        }
      }
    }
  }
}

Headers, cookies, path and query parameters are emitted under parameters; form and JSON bodies become a requestBody with the matching media type. -f oas2 produces the Swagger 2.0 shape instead, where a body parameter is an in: formData / in: body entry and cookies ride along as a Cookie header.

Documents are emitted as OpenAPI 3.0.3. A scan that discovers an HTTP QUERY route is emitted as 3.2.0 instead, because 3.0.x has no query operation.