OpenAPI
Provides OpenAPI (Swagger) specification documents describing Drupal's REST APIs.
openapi
Install
composer require 'drupal/openapi:8.x-2.3'
composer require 'drupal/openapi:8.x-2.1'
Overview
The OpenAPI module generates machine-readable API documentation following the OpenAPI (formerly Swagger) specification standard. This enables automatic generation of API documentation, client code generation, and API testing capabilities for Drupal sites.
This is a foundational module that provides the core framework and plugin system for generating OpenAPI specifications. To use it, you must install integration modules such as OpenAPI REST for Drupal Core's REST module or OpenAPI JSON:API for the JSON:API module.
The generated OpenAPI specifications can be used with tools like Swagger Editor, Swagger Codegen, Postman, and various API documentation viewers. The module also integrates with the OpenAPI UI module to provide in-browser documentation viewing using tools like ReDoc or Swagger UI.
Features
- Generates OpenAPI 2.0 (Swagger) specification documents in JSON format for Drupal REST APIs
- Plugin-based architecture allowing other modules to provide API documentation generators for different API implementations
- Built-in support for multiple authentication methods including Basic Auth, OAuth2, and CSRF Token authentication
- Admin interface listing all available API generators with links to download specifications or explore documentation
- Integration with OpenAPI UI module for interactive API documentation viewing within Drupal
- Filtering options to generate specifications for specific entity types or bundles
- Automatic detection of security definitions based on enabled authentication providers
- Schema validation and cleaning utilities for generated specifications
Use Cases
Generating API Documentation for Developers
Use OpenAPI to generate comprehensive REST API documentation for your Drupal site. After installing the module with an integration module (openapi_rest or openapi_jsonapi), developers can access /openapi/rest?_format=json or /openapi/jsonapi?_format=json to download the complete API specification. This JSON file can be imported into tools like Swagger Editor for interactive browsing or Swagger Codegen to generate client libraries in various programming languages.
Interactive API Explorer
Combine OpenAPI with the OpenAPI UI and openapi_ui_redoc modules to provide an in-browser API documentation interface. Navigate to /admin/config/services/openapi/redoc/rest or /admin/config/services/openapi/redoc/jsonapi to explore your API interactively. Developers can see all available endpoints, request/response schemas, and authentication requirements without leaving the browser.
API Client Code Generation
Download the OpenAPI specification and use Swagger Codegen or OpenAPI Generator to automatically create client libraries for your Drupal API in languages like JavaScript, Python, PHP, Java, and many others. This ensures type-safe API consumption and reduces development time for applications integrating with your Drupal site.
Entity-Specific Documentation
Generate documentation for specific entity types or bundles by passing options in the URL. For example, /openapi/rest?_format=json&options[entity_type_id]=node&options[bundle_name]=article generates documentation only for article nodes. This is useful when creating focused documentation for specific API consumers.
API Testing with Postman
Import the generated OpenAPI specification into Postman or similar API testing tools. The specification includes endpoint URLs, authentication requirements, request parameters, and expected responses, making it easy to create test collections and validate API behavior.
Custom API Documentation Generator
Create a custom OpenAPI generator plugin for a custom API module or unique API implementation. Extend OpenApiGeneratorBase and implement methods like getPaths(), getDefinitions(), getTags(), and getApiName() to generate specifications matching your API structure. Place the plugin in your module's src/Plugin/openapi/OpenApiGenerator directory with the @OpenApiGenerator annotation.
Tips
- Use the openapi_ui_redoc module for a clean, responsive documentation interface that works well for both developers and stakeholders
- Filter large API specifications using URL options like entity_type_id and bundle_name to generate focused documentation for specific use cases
- Bookmark the direct JSON download URL (/openapi/rest?_format=json) for quick access during development
- The generated specification includes scheme (http/https), host, and basePath information automatically detected from your site's configuration
- Security definitions are automatically populated based on enabled authentication modules - enable basic_auth or Simple OAuth to include those authentication methods
- Custom generators can use the 'exclude' option to filter out specific entity types or bundles from the specification
Technical Details
Admin Pages 1
/admin/config/services/openapi
The main administration page for OpenAPI that lists all available API documentation generators. This page provides an overview of OpenAPI functionality and links to download specifications or view interactive documentation.
Permissions 1
Hooks 1
hook_openapi_generator_alter
Allows modules to alter the OpenAPI generator plugin definitions. Called during plugin discovery to modify available generators.
Troubleshooting 5
Install an integration module that provides generator plugins. For Core REST, install openapi_rest. For JSON:API, install openapi_jsonapi. Without these integration modules, the OpenAPI module has no APIs to document.
Ensure the user has the 'access openapi api docs' permission. This permission is required to view the OpenAPI admin page and download specifications.
Make sure the corresponding API module (REST or JSON:API) is enabled and has resources configured. For REST, enable and configure REST resources at /admin/config/services/rest. For JSON:API, ensure entity types are enabled for JSON:API access.
Install the openapi_ui module along with a UI library module like openapi_ui_redoc or openapi_ui_swagger_ui. Without these modules, only the specification download link will be available.
The module automatically detects authentication providers registered with Drupal. Ensure modules like basic_auth, oauth2 (Simple OAuth), or other authentication modules are properly enabled and configured.
Security Notes 3
- The 'access openapi api docs' permission controls access to API documentation. Consider carefully who should have this permission, as API documentation may reveal the structure of your site's data
- API specifications are generated based on the current user's permissions and may include endpoints the user can see but not necessarily access
- Be cautious when exposing OpenAPI documentation publicly, as it provides detailed information about your site's API structure that could be used for reconnaissance