OpenAPI Spec Handler

The OpenAPI Spec handler serves a public version of your OpenAPI specification file. The handler strips Zuplo gateway configuration (such as x-zuplo-* extensions) and enriches the spec with data based on the gateway implementation. For example, if a route uses API key authentication, the handler automatically documents the Authorization header in the generated OpenAPI spec.

Setup via Portal

The OpenAPI Spec Handler can be added to any route using the Route Designer. Open the Route Designer by navigating to the Code tab then click routes.oas.json. Inside any route, select OpenAPI Spec from the Request Handlers drop-down.

The handler defaults to the OpenAPI file currently open, but you can change it to serve a different OpenAPI file via the dropdown.

Setup via routes.oas.json

Add the OpenAPI Spec handler manually to the routes.oas.json file with the following route configuration:

Code
"paths": {
  "/openapi": {
    "get": {
      "summary": "OpenAPI Specification",
      "x-zuplo-route": {
        "corsPolicy": "none",
        "handler": {
          "export": "openApiSpecHandler",
          "module": "$import(@zuplo/runtime)",
          "options": {
            "openApiFilePath": "./config/routes.oas.json"
          }
        },
        "policies": {
          "inbound": []
        }
      }
    }
  }
}

Options

The OpenAPI Spec handler accepts the following options:

• openApiFilePath (required): The file path of an OpenAPI file within the config folder.
  • Type: string
  • The file name must end with .oas.json.
  • Example: "./config/routes.oas.json"

How It Works

When a request hits the route with this handler, the handler:

1. Reads the specified OpenAPI file from the project configuration.
2. Removes all Zuplo-specific extensions (x-zuplo-* properties) that are not relevant to API consumers.
3. Enriches the spec with information derived from the gateway configuration, such as authentication requirements inferred from applied policies.
4. Returns the cleaned and enriched OpenAPI spec as a JSON response.

Common Use Cases

• Developer portal integration: Serve the OpenAPI spec at a known endpoint for developer portals or documentation tools to consume.
• Client SDK generation: Provide an endpoint that CI/CD pipelines or developers can use to generate client SDKs from the latest API spec.
• API discovery: Expose the spec so that API consumers can explore available endpoints and their requirements.