Server Open Api.md

Open Api

When mapping routes, you can use attributes to define Open Api metadata

// src/api/get.php
use function CatPaw\Web\success;
use CatPaw\Web\Attributes\ProducesItem;

return
    #[ProducesItem(200, 'text/plain', 'Success!', string::class)]
    fn () => success('hello')->item();

Available Attributes

Attribute Name	Description
Consumes	Annotate a route handler to describe the content it consumes.
Produces	Annotate a route handler to describe the content it produces.
ProducesItem	Annotate a route handler to describe the content it produces using a predefined structure offered by catpaw.
ProducesPage	Annotate a route handler to describe the content it produces using a predefined paged structure offered by catpaw.
ProducesError	Annotate a route handler to describe an error. Must be paired with Produces.
ProducesItemError	Annotate a route handler to describe an error. Must be paired with ProducesItem.
ProducesPageError	Annotate a route handler to describe an error. Must be paired with ProducesPage.
Summary	Annotate a route handler with a short description.
Tag	Annotate a route handler with a tag. SwaggerUi will graphically group routes based on these tags.
Example	Annotate a route handler parameter to provide an example in SwaggerUi.
Header	Annotate a route handler parameter to inject an http header.
Param	Annotate a route handler parameter to inject and configure a path parameter.
Query	Annotate a route handler parameter to inject a query string.

SwaggerUi & Json Metadata

For SwaggerUi to work as intended, you will need to export all this metadata you define through attributes as Json

// src/api/openapi/get.php
use function CatPaw\Web\success;
use CatPaw\Web\Interfaces\OpenApiInterface;
return static fn (OpenApiInterface $oa) => success($oa->data())->as('application/json');

Then feed the data to your SwaggerUi (or any other user interface compliant with Open Api).