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; bodies become a requestBody with the matching media type:

• json → application/json
• form → application/x-www-form-urlencoded (or multipart/form-data when a sibling file field is present)
• file → multipart/form-data with format: binary (co-located form fields ride along; file-only uploads still get multipart rather than a misleading query parameter)
• xml → application/xml (Play asXml / Tapir xmlBody and similar whole-body XML params)

-f oas2 produces the Swagger 2.0 shape instead, where a body parameter is an in: formData / in: body entry (type: file under multipart for uploads) 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.