elenyum/open-api

This bundle generates documentation and returns JSON formatted according to the OpenAPI specification.

1.0 2024-03-30 17:12 UTC

Requires

• php: >=8.1
• ext-json: *
• symfony/console: ^5.4|^6.0|^7.0
• symfony/framework-bundle: ^5.4.24|^6.0|^7.0
• symfony/options-resolver: ^7.0
• symfony/property-info: ^7.0
• symfony/validator: ^7.0
• zircote/swagger-php: ^4.2.15

Requires (Dev)

• doctrine/annotations: ^2.0
• mikey179/vfsstream: ^1.6
• phpunit/phpunit: ^11.0
• symfony/serializer: ^7.0

MIT

• Elenyum

• documentation
• rest
• api
• doc

README

This bundle generates documentation and returns JSON formatted according to the OpenAPI specification.

Install

composer require elenyum/open-api

Configuration

For adding configuration, create a config file in the project root directory, /config/packages/elenyum_open_api.yaml. In the config file add:

elenyum_open_api:
    documentation:
        info:
            title: My project name
            description: My project description
            version: 1.0.0

To add a route to get the json specification add to project root file /config/routes/elenyum_open_api.yaml

width config example:

app.openapi:
  path: /v1/doc
  methods: GET
  defaults: { _controller: elenyum_open_api }

Cache Configuration

• cache.enable:
  Indicates whether caching is activated. Default: false.

• cache.item_id:
  Sets the cache item identifier. Default: elenyum_open_api.

Example:

yaml

cache:
  enable: true
  item_id: 'my_custom_cache_id'

Documentation Configuration

Serves as a foundation for creating API documentation using attributes as keys.

• documentation.info.title:
  The title of the application in the documentation: My App.

• documentation.info.description:
  The description of the application in the documentation: Description service.

• documentation.info.version:
  The version of the application in the documentation: 1.0.0.

Example:

yaml

documentation:
  info:
    title: 'My App'
    description: 'Description service'
    version: '1.0.0'

Other Configuration

Filters the routes that will be documented and manages their visibility in the generated documentation.

• path_patterns:
  An array of regex patterns to match against the path for including routes.

• host_patterns:
  An array of regex patterns to match against the host for including routes.

• name_patterns:
  An array of regex patterns to match against the route name for including routes.

• with_tag:
  A boolean indicating if routes should be filtered by tag (annotations).

• disable_default_routes:
  A boolean indicating if default routes without explicit OpenAPI annotations should be excluded.

Example

yaml

path_patterns: ['^/api']
host_patterns: ['^api\.']
name_patterns: ['^api_v1']
with_tag: true
disable_default_routes: false