Api docs

Skill api-platform/skillset/skills/api-docs

API Platform agent skills

Install

npx -y skills add api-platform/skillset --skill api-docs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
24 stars24 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Customizes OpenAPI documentation for API Platform resources. Use whenever the user mentions OpenAPI/Swagger output, API docs, descriptions or examples on endpoints or properties, custom response documentation, hiding operations or resources from docs, or decorating the OpenAPI factory — even for small requests like 'document this field'.

SKILL.md

4.4 KB, as published. Nobody here has run it

Customizing API Documentation

API Platform generates OpenAPI v3 documentation automatically. Customize it using attributes.

Global Info & Security Schemes (YAML)

Set the API-wide title, version, description and auth schemes in config/packages/api_platform.yaml:

api_platform:
    openapi:
        info:
            title: 'My API'
            version: '1.0.0'
            description: 'What this API does.'
        components:
            securitySchemes:
                Bearer:
                    type: http
                    scheme: bearer
                    bearerFormat: JWT

Operation-Level Customization

use ApiPlatform\Metadata\Post;
use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\Response as OpenApiResponse;

#[Post(
    openapi: new Operation(
        summary: 'Create a new order',
        description: 'Creates an order and sends confirmation email.',
        responses: [
            '201' => new OpenApiResponse(description: 'Order created successfully'),
            '422' => new OpenApiResponse(description: 'Validation failed'),
        ]
    )
)]
class Order {}

Property Documentation

use ApiPlatform\Metadata\ApiProperty;

class Order
{
    #[ApiProperty(description: 'The unique identifier', example: 1)]
    public int $id;

    #[ApiProperty(
        description: 'Current status',
        example: 'pending',
        openapiContext: ['enum' => ['pending', 'shipped', 'delivered']]
    )]
    public string $status;

    #[ApiProperty(
        genId: false,
        types: ['https://schema.org/sender'],
        openapiContext: [
            'example' => ['address' => '[email protected]', 'name' => 'John'],
        ],
    )]
    public Recipient $from;
}

Use genId: false on embedded objects (non-IRI properties) to suppress @id generation.

Hiding from Documentation

// Hide entire resource
#[ApiResource(openapi: false)]

// Hide specific operation
#[Get(openapi: false)]

// Hide from Hydra entrypoint only (keep in OpenAPI)
#[Get(hydra: false)]

Custom Parameters

use ApiPlatform\Metadata\HeaderParameter;

#[Post(
    parameters: [
        'X-Idempotency-Key' => new HeaderParameter(
            description: 'Unique key to prevent duplicate processing',
            required: true,
        ),
    ],
)]

OpenApiFactory Decorator (Global Customization)

Decorate the built-in factory for global changes like custom server URLs:

<?php
namespace App\OpenApi;

use ApiPlatform\OpenApi\Factory\OpenApiFactoryInterface;
use ApiPlatform\OpenApi\Model;
use ApiPlatform\OpenApi\OpenApi;

final class OpenApiFactory implements OpenApiFactoryInterface
{
    public function __construct(
        private readonly OpenApiFactoryInterface $decorated,
        private readonly string $openapiUrl,
    ) {}

    public function __invoke(array $context = []): OpenApi
    {
        $openApi = $this->decorated->__invoke($context);

        return $openApi->withServers([
            new Model\Server($this->openapiUrl),
        ]);
    }
}

App\OpenApi\OpenApiFactory:
    decorates: 'api_platform.openapi.factory'
    arguments:
        $openapiUrl: '%env(OPENAPI_URL)%'

Laravel

All the attribute-level customization — operation openapi: new Operation(...), #[ApiProperty] description/example/openapiContext, openapi: false, hydra: false, HeaderParameter — is framework-neutral and works unchanged. Only the global pieces differ:

Global title/version/description are top-level keys in config/api-platform.php ('title', 'version', 'description'); there is no openapi.info YAML. Security schemes are configured under the swagger_ui block (apiKeys, oauth, http_auth) in the same file, and openapi.tags is available there too.
To decorate the OpenAPI factory, bind your decorator in a service provider with the container's extend() (resolving the inner OpenApiFactoryInterface) instead of the Symfony decorates: YAML — the OpenApiFactoryInterface and withServers(...) API are identical.