Why does Membrane API Gateway return 404 OpenAPI not found?

A request for an OpenAPI document or its Swagger UI under /api-docs named an id for which no document is deployed. Ids are computed from the title and version of the document, so changing them breaks old links.

How do I find the correct OpenAPI document id in Membrane?

Open /api-docs on the gateway. The overview lists all deployed documents with links to the documents and their Swagger UI. To get stable ids, set x-membrane-id in the info section of the OpenAPI document.

Does production mode hide the details of this Membrane error?

No. For this error Membrane sends the detail and the link to the documentation even when production mode is enabled with production: true. The detail only repeats the requested id.

404 Not Found: OpenAPI Document Not Found

Membrane API Gateway returns 404 Not Found when a request for an OpenAPI document or its Swagger UI, such as /api-docs/{id} or /api-docs/ui/{id}, names an id for which no OpenAPI document is deployed, or names no id at all. The response comes from the openapiPublisher of an API or from the gateway-wide apiDocs overview.

The Error Response

The response contains the status 404 Not Found, the problem type https://membrane-api.io/problems/user/openapi and a link to this page. The type user/openapi means that the request caused the problem while it was handled by an OpenAPI feature, not an internal failure of the gateway. Title and detail depend on the case:

OpenAPI Not Found

The title is OpenAPI not found and the detail is OpenAPI document with the id fruitshop-v2-0 not found. with the requested id. This is the usual case.

No OpenAPI Document Id

The title is No OpenAPI document id and the detail is Please specify an id of an OpenAPI document. Path should match this pattern: /api-docs/ui/<<id>>. This case is rare. In practice, it only occurs with apiDocs when /api-docs/ui/ is called without an id.

How Document Ids Work

Membrane gives each OpenAPI document an id, which it computes from info.title and info.version. For the title Fruit Shop API and the version 1.0, the id is fruit-shop-api-v1-0. The document is then available under /api-docs/fruit-shop-api-v1-0 and its Swagger UI under /api-docs/ui/fruit-shop-api-v1-0. See OpenAPI Configuration and Validation and API Overview and Swagger UI.

Common Causes

The Id Does Not Exist

The link contains a typo or is outdated. Because the id is derived from the title and version, changing either of them in the document changes the id and breaks existing links and bookmarks.

Extra Characters in the Id

Everything after /api-docs/ui/ is treated as the id. A trailing slash or a query string, as in /api-docs/ui/fruitshop-v2-0?x=1, becomes part of the id, and no document is found.

The Id Is Missing

The path /api-docs/ui/ was called without an id, which leads to No OpenAPI document id.

Two Documents Have the Same Id

If two documents in an API have the same title and version, Membrane keeps the second one under a suffixed id such as ...-0 and logs a warning. apiDocs keeps only the first document for an id that occurs in more than one API. Links that expect the other document then point to the wrong one or fail.

How to Fix It

Open /api-docs on the gateway for the list of deployed documents, and use the links it provides.
Remove trailing slashes and query strings from links to /api-docs/ui/{id}.
As an operator, check the log for duplicate id warnings, and give each document a unique title and version.

To keep ids stable when the title changes, set x-membrane-id in the info section of the OpenAPI document:

info:
  title: Fruit Shop API
  version: '1.0'
  x-membrane-id: fruitshop

info:
  title: Fruit Shop API
  version: '1.0'
  x-membrane-id: fruitshop

The id still includes the version, resulting in fruitshop-v-1-0.

Details in Production Mode

Unlike most errors, this response is not shortened in production mode. It contains the detail and the link to this page even with production: true. The detail only repeats the requested id, and the deployed ids are listed publicly under /api-docs anyway.