Skip to content

feat(openapi): Built-in OpenAPI spec service with namespace scanning support #144

Description

@usernane

Problem Statement

Every project that uses #[RestController] needs to manually create a service to expose the OpenAPI spec. This is boilerplate that belongs in the library itself, since webfiori/http already owns the API layer and the OpenAPIGenerator.

Proposed Solution

Add two things:

1. Namespace scanning to OpenAPIGenerator

A new method that scans a namespace for #[RestController] classes and generates the spec automatically:

$generator = new OpenAPIGenerator();
$spec = $generator->generateFromNamespace('App\\Apis', 'API Title', '1.0.0', '/apis');

This complements the existing explicit-instance approach:

$spec = $generator->generate([new ProductService(), new UserService()], ...);

Both produce the same OpenAPIObj. Users pick whichever fits:

  • Explicit instances — full control over which services to include and ordering
  • Namespace scan — convenient auto-discovery, no manual maintenance

2. Built-in OpenAPISpecService

A ready-to-use service bundled in the library that exposes the generated spec:

#[RestController('openapi', 'OpenAPI specification endpoint')]
class OpenAPISpecService extends WebService {
    // User configures namespace + base path
    // GET returns the JSON spec directly
}

Users register it like any other service, passing namespace and base path as config.

Alternatives Considered

  • Putting this in webfiori/framework — rejected because API docs belong with the API layer itself
  • Relying on a central manager — the new framework design has each service working independently, so namespace scanning is the right discovery mechanism

Breaking Change

No

Additional Context

The namespace scanning would use reflection to find classes with #[RestController] attribute, instantiate them, and pass them to the existing generate() method internally.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions