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 writes both OAS 2.0 (Swagger) and OAS 3.x. Pass -u to set the server address: it fills servers in OAS 3 and host / schemes in OAS 2. Without it, OAS 3 uses http://localhost and OAS 2 leaves host out.

Usage

OAS 3.0 (recommended):

noir scan . -f oas3

OAS 2.0:

noir scan . -f oas2

Example Output

The document 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.

A path item holds one operation per verb, so when two projects of a monorepo declare the same route (POST /items in both services/orders and services/users), their endpoints share one operation and their parameters are merged. Rather than let that pass unnoticed, Noir lists the projects on the operation as x-noir-projects and logs a warning naming them. Operations that only one project declares carry no such key, and neither does a scan without projects. To get a separate operation for each, scan each project on its own (-b services/orders). The same applies to -f oas2.