OpenAPI Specification (OAS) Output

The OpenAPI Specification (OAS) is a standard, language-agnostic interface for describing RESTful APIs. By generating an OAS document from your codebase, you can easily create interactive API documentation, set up automated testing, or import your API definition into a variety of other tools.

Noir can generate both OAS 2.0 (formerly known as Swagger) and OAS 3.0 specifications.

How to Generate an OpenAPI Specification

To generate an OAS document, use the -f or --format flag with either oas2 or oas3.

• For OAS 3.0 (recommended):

  noir -b . -f oas3
  

• For OAS 2.0:

  noir -b . -f oas2
  

This will output a JSON document that conforms to the specified OpenAPI version.

Example OAS 3.0 Output

Here is a sample of the output for the oas3 format:

{
  "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"
          }
        ]
      }
    }
    // ... and so on for all other endpoints
  }
}

By using this feature, you can automatically generate a comprehensive and accurate API specification directly from your source code, saving you time and ensuring that your documentation is always up-to-date.