Custom authentication header is not exposed in the OpenAPI documentation of a Published REST service

Issue

A Published REST service is secured with a custom authentication microflow that validates an API token sent in a custom HTTP header, for example AuthToken: <token>. The generated OpenAPI documentation is available through an endpoint such as /rest/myservice/v1/openapi.json, but the generated document does not contain any security metadata, such as securitySchemes or security definitions.

As a result, the Swagger UI page of the published service does not offer any field or Authorize option to provide the custom header value, so test calls executed from the Swagger UI are sent without the required token and are rejected by the authentication microflow.

Environment

Studio Pro (all versions)

Cause

The OpenAPI document and the Swagger UI page of a Published REST service are generated by the Mendix Runtime based on the service definition in the model (resources, operations, parameters, and message definitions). When the authentication of the service is handled by a custom authentication microflow, the custom HTTP header that the microflow reads is not part of the service definition, so the Mendix Runtime has no information about it and cannot add a corresponding securitySchemes entry to the generated OpenAPI document.

Solution/Workaround

The generated OpenAPI document cannot be extended with security definitions for a custom authentication microflow. Use one of the following approaches to document and test the custom header:

• Publish your own OpenAPI document instead of relying on the generated one:

  1. Create an OpenAPI document (JSON or YAML) that describes the service and includes the securitySchemes definition for the custom header (an API key security scheme of type apiKey with in: header and name: AuthToken).

  2. Add the document to the project as a resource, or serve it from a dedicated published REST operation.

  3. Point the consumers and/or your own Swagger UI instance to this document instead of the generated openapi.json.

• Define the token as an explicit HTTP header parameter on each published operation, so that it becomes part of the generated OpenAPI document and can be filled in from the Swagger UI. In this case, the value is read from the operation parameter instead of being validated only by the custom authentication microflow.

• Test the service with a client that allows setting custom headers (for example, Postman or cURL) instead of the built-in Swagger UI page.

Additional information

• Mendix documentation:
  • Published REST Services
  • Published REST Operation
  • Authorization header parameter not received in microflow