Data API builder REST API documentation with Swagger / OpenAPI

  • Article

The OpenAPI specification is a programming language-agnostic standard for documenting HTTP APIs. Data API builder supports the OpenAPI standard with its ability to:

  • Generate information about all runtime configuration defined entities that are REST enabled.
  • Compile the information into a format that matches the OpenAPI schema.
  • Exposes the generated OpenAPI schema via a visual UI (Swagger) or a serialized file.

OpenAPI description document

Data API builder generates an OpenAPI description document using the provided runtime configuration and the database object metadata for each REST enabled entity defined. The schema file is generated using functionality provided by the OpenAPI.NET SDK. Currently, the schema file is generated in adherence to OpenAPI Specification v3.0.1 formatted as JSON.

The OpenAPI description document can be fetched from Data API builder from the path:

GET /{rest-path}/openapi

Note

By default, the rest-path value is api and is configurable. For more information, see REST configuration

SwaggerUI

Swagger UI offers a web-based UI that provides information about the service, using the generated OpenAPI specification.

In Development mode, Data API builder enables viewing the generated OpenAPI description document from a dedicated endpoint:

GET /swagger

The "Swagger" endpoint isn't nested under the rest-path in order to avoid naming conflicts with runtime configured entities.

Related content