Why does Membrane API Gateway return Error generating OpenAPI overview?

The apiDocs plugin failed while building the API overview or a single OpenAPI document. Usually one of the OpenAPI documents lacks an info object or has a servers entry without a valid url.

How do I fix Error generating OpenAPI overview in Membrane?

Validate the OpenAPI documents of your APIs. Each needs an info object with title and version, and every servers entry needs a valid url. Check the gateway log for the full exception.

How do I hide the details in Membrane error responses?

Enable production mode by adding a configuration document with production: true to your apis.yaml. Membrane then leaves out detailed information from error responses.

500 Internal Server Error: Error Generating OpenAPI Overview

Membrane API Gateway returns 500 Internal Server Error with the detail Error generating OpenAPI overview! when the apiDocs plugin fails to build the API overview or a single OpenAPI document. The cause is usually one of the OpenAPI documents served by the gateway, sometimes a bug in Membrane. The client did nothing wrong.

The Error Response

The response contains the status 500 Internal Server Error, the detail Error generating OpenAPI overview!, the problem type https://membrane-api.io/problems/internal and a link to this page. The type internal means that the gateway failed while processing the exchange.

What the apiDocs Plugin Does

The apiDocs plugin answers with an HTML or JSON overview of all APIs deployed from OpenAPI documents, and it serves each document on its own. Requests for the Swagger UI under /api-docs/ui/ do not produce this error.

Common Causes

A Servers URL Cannot Be Parsed

When a single OpenAPI 3 document is requested, Membrane rewrites every servers[].url to the address of the gateway. A server URL that is not a valid URI makes this fail, and so does a servers entry without a url.

A Document Has No Info Object

The JSON overview, which is returned when the Accept header does not contain html, reads info.title and info.version from every document. A document without an info object fails here.

The HTML Overview Could Not Be Rendered

Rendering the template of the HTML overview failed. This is rare and usually indicates a bug in Membrane.

How to Fix It

Check the gateway log. Membrane logs the full exception at error level.
Validate the OpenAPI documents configured in the openapi elements of your APIs. Each needs info with title and version, and every servers entry needs a valid url:

openapi: 3.0.3
info:
  title: Shop API
  version: 1.0.0
servers:
  - url: https://api.example.com/shop/v2
paths: {}

openapi: 3.0.3
info:
  title: Shop API
  version: 1.0.0
servers:
  - url: https://api.example.com/shop/v2
paths: {}

If the documents are valid, report the problem with the stack trace on GitHub Issues.

Hide Details in Production

By default, Membrane runs in development mode and adds details to error responses that help you find the problem, including the link to this page. These details may reveal information about your setup. In production, turn them off:

configuration:
  production: true

configuration:
  production: true

Add the configuration document to your apis.yaml and separate it from the APIs with ---.

In production mode, the title of this error is replaced by Internal Server Error, and the response only says Internal details are hidden. See server log (key: ...). Search the gateway log for that key to find the full error message.