README

Auto-Generate documentation API for GollumSF\RestBundle : https://github.com/GollumSF/rest-bundle

Requirements:

• PHP >= 8.2
• Symfony 6.4, 7.x or 8.0

Installation:

composer require gollumsf/rest-doc-bundle

config/bundles.php

return [
    // [ ... ]
    GollumSF\RestBundle\GollumSFRestDocBundle::class => ['all' => true],
];

Configuration:

All configurations is optionals. Edit file config/packages/gollum_sf_rest_doc.yaml :

gollum_sf_rest_doc:

    #################
    # Documentation #
    #################

    title: 'REST Api'                      # optional, default : REST Api
    version: '1.0.0'                       # optional, default : 1.0.0
    description: 'Api general description' # optional, default : null

    external_docs:                                          # optional
        url: 'https://github.com/GollumSF/rest-doc-bundle'  # required
        description: 'External documentation description'   # optional, default : null

    ##############
    # Host / URL #
    ################

    host:                                  # optional, default : null (return current host url)
        - 'dev.api.com'
        - 'preprod.api.com'
        - 'prod.api.com'
    default_host: 'dev.api.com'            # optional, default : null (return first item to host list)
    protocol:                              # optional, default : null (return current sheme url)
        - 'http'
        - 'https'
    default_protocol: 'http'               # optional, default : null (return first item to protocol list)

    ############
    # Security #
    ############

    security:                              # optional (No security token if not defined)
        my_first_configuration:
            type: 'authorization_bearer'   # required, authorization_bearer generate classic authorization bearer
            name: 'Authorization'          # optional, default: Authorization, the header name
            scheme: 'BEARER'               # optional, default: BEARER, the scheme in header value
            defaultValue: 'TOKEN_DEMO'     # optional, the default token value for demo

        my_second_configuration:
            type: 'query_param'            # required, query_param generate query string token
            name: 'token'                  # optional, default: token, the query name
            defaultValue: 'TOKEN_DEMO'     # optional, the default token value for demo
        my_custom_configuration:
            type: 'custom'                 # required, custom generate a custom configuration based on:
            defaultValue: 'TOKEN_DEMO'     # optional, the default token value for demo
            data:                          # required, Data based on securitySchemes content
                type: 'http'               #  - show : https://swagger.io/docs/specification/authentication/
                scheme: 'basic'

Integration with Swagger:

#app/config/routing.yml
gsf_restbundle_swagger:
    resource: "@GollumSFRestDocBundle/Resources/config/swagger_routing.yml"
    prefix: /api-docs

Integration with OpenApi JSON:

gsf_restbundle_openapi:
    resource: "@GollumSFRestDocBundle/Resources/config/openapi_routing.yml"
    prefix: /api-docs.json

Attributes:

The documentation is automatically generated from your controllers using #[Serialize] and #[Unserialize] attributes from RestBundle. No additional configuration is needed for basic API documentation.

You can optionally enrich the generated documentation with these attributes:

ApiDescribe (on controller methods)

Override or add metadata for a specific route:

use GollumSF\RestDocBundle\Annotation\ApiDescribe;

#[ApiDescribe(entity: Book::class, serializeGroups: ['book_get'])]
public function list() { ... }

ApiEntity (on entity classes)

Add description and URL metadata to an entity:

use GollumSF\RestDocBundle\Annotation\ApiEntity;

#[ApiEntity(description: 'A book entity', url: '/api/books')]
class Book {
    // ...
}

ApiProperty (on entity properties)

Override the auto-detected type or description of a property:

use GollumSF\RestDocBundle\Annotation\ApiProperty;

class Book {
    #[ApiProperty(type: 'integer')]
    private int $id;

    #[ApiProperty(type: 'string')]
    private string $title;
}