api_wrapper

🇵🇸

A Drupal module that allows you to automatically expose service methods as HTTP endpoints using PHP 8 Attributes, and to generate a Swagger-like API documentation page without writing YAML routes manually.
The module scans services annotated with #[ApiWrap] and #[Endpoint], dynamically registers routes, and builds a navigable API documentation UI.

🧠 Core Concepts

#[ApiWrap] Attribute (Class-level)

Marks a service as an API wrapper and defines its base configuration.

Arguments

Name Type Description basePath string Base URL path for all endpoints label string API display name description string API description docPath string Custom documentation route (optional)

If docPath is omitted:

/api-wrapper/docs/{basePath}

#[Endpoint] Attribute (Method-level)

Defines a public API endpoint for a service method.

Arguments

Name Type Description method string HTTP method path string Endpoint path label string Human-readable label description string Endpoint description

🔀 Dynamic Route Generation

Routes are generated at runtime by ApiWrapperRoutesProvider.

GET /dummy-json/users/{id}
POST /dummy-json/carts/add

If a method parameter has a default value, an additional route is generated.

🔧 Supported Method Parameters

• Scalar types → Path parameters
• Symfony Request → Ignored
• Default values → Route defaults

📚 API Documentation System

1. Services scanned via Reflection
2. Endpoint metadata collected
3. Stored in Drupal State:

api_wrapper.documentation.{apiName}

• Rendered by ApiWrapperDocumentationController
• Twig theme: api_wrapper_documentation

🌐 Documentation Routes

/api-wrapper/docs/{apiName}

Or custom via docPath.

🎨 Swagger-like UI

• Grouped endpoints
• HTTP badges
• Parameter list
• Clickable GET endpoints
• Base URL display
• Light/Dark toggle (localStorage)

🎨 Customizing the API Documentation Theme

The API wrapper module provides a default Twig template:
api-wrapper-documentation.html.twig

You can customize the documentation UI by providing your own Twig template
inside your custom module or theme.

How to override

1. Create a templates/ folder in your module or theme (if missing).
2. Create api-wrapper-documentation.html.twig.
3. Copy the default template structure and adjust HTML, CSS, or Twig logic.
4. Clear cache (drush cr or admin UI).

🧪 Example API Implementation

#[ApiWrap(...)]
final class DummyJsonApi {

  #[Endpoint(method: 'GET', path: 'users')]
  public function users(): JsonResponse {}

  public function user(int $id): JsonResponse {}

  public function carts(): JsonResponse {}

  public function cart(int $id): JsonResponse {}

  #[Endpoint(method: 'POST', path: 'carts/add')]
  public function addCart(array $cartData): JsonResponse {}
}

Generated routes:

GET  /dummy-json/users
GET  /dummy-json/users/{id}
GET  /dummy-json/carts
GET  /dummy-json/carts/{id}
POST /dummy-json/carts/add

🔐 Permissions

access content

⚠️ Limitations

• No OpenAPI export
• No schema generation
• No POST body docs
• Internal APIs focus

🚀 Possible Future Improvements

• OpenAPI 3.0
• Schema support
• Per-endpoint permissions
• Query params
• Auth helpers