API Wrapper

🇵🇸

🧠 Core Concepts

#[ApiWrap] Attribute (Class-level)

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

Arguments

If docPath is omitted:

/api-wrapper/docs/{basePath}

#[Endpoint] Attribute (Method-level)

Defines a public API endpoint for a service method.

Arguments

🔀 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