mirror of
https://github.com/retailcrm/NelmioApiDocBundle.git
synced 2025-04-02 21:36:14 +03:00
Generates documentation for your REST API from annotations
babf788636
* Adding ``header_block`` Twig Block
In attempting to remove the default green header from the API docs (I am integrating the docs into a site that already has a header), I have found that the only possible way to do so is to overwrite the entire ``index.html.twig`` file. This is because the existing ``{% header %}`` twig tags are placed *inside* the ``<header>`` HTML tags. So, if one overrides the ``{% header %}`` block, it only adjusts the header content, as opposed to allowing control over the entire header object.
To resolve this problem I considered two methods:
- Move the existing ``{% header %}`` tags _*outside*_ of the ``<header>`` tags. This would resolve the problem in the simplest fashion, but would be a breaking change for those currently overriding the block.
- Add a new twig block, placing its tags *_outside_* the existing ``<header>`` tags. This would leave the existing functionality as-is, and would not break any current implementations.
I chose the latter for the reasons specified above, and suggested the name ``{% header_block %}``. Thanks for considering this proposal.
* Add Location of Original Twig Template
This doc page advises that one can `have a look at the original template to see which blocks can be overridden`, but does not say where the original template can be found. This edit adds that information so that users don't have to resort to searching for keywords (like I just had to).
Note that I haven't run any tests as this is a docs-only change.
|
||
|---|---|---|
| .github/workflows | ||
| Annotation | ||
| Command | ||
| Controller | ||
| DependencyInjection | ||
| Describer | ||
| Exception | ||
| Form/Extension | ||
| Model | ||
| ModelDescriber | ||
| OpenApiPhp | ||
| PropertyDescriber | ||
| Render | ||
| Resources | ||
| RouteDescriber | ||
| Routing | ||
| Tests | ||
| Util | ||
| .gitattributes | ||
| .gitignore | ||
| .php_cs.dist | ||
| .styleci.yml | ||
| .symfony.bundle.yaml | ||
| ApiDocGenerator.php | ||
| CHANGELOG.md | ||
| composer.json | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| NelmioApiDocBundle.php | ||
| phpunit | ||
| phpunit.bat | ||
| phpunit.xml.dist | ||
| README.md | ||
| update-js.sh | ||
| UPGRADE-3.0.md | ||
| UPGRADE-4.0.md | ||
NelmioApiDocBundle
The NelmioApiDocBundle bundle allows you to generate a decent documentation for your APIs.
Migrate from 3.x to 4.0
To migrate from 3.x to 4.0, follow our guide.
Version 4.0 brings OpenAPI 3.0 support. If you want to stick to Swagger 2.0, you should use the version 3 of this bundle.
Migrate from 2.x to 3.0
To migrate from 2.x to 3.0, follow our guide.
Installation
Open a command console, enter your project directory and execute the following command to download the latest version of this bundle:
composer require nelmio/api-doc-bundle
Documentation
Read the documentation on symfony.com
Contributing
See CONTRIBUTING file.
Running the Tests
Install the Composer dependencies:
git clone https://github.com/nelmio/NelmioApiDocBundle.git
cd NelmioApiDocBundle
composer update
Then run the test suite:
./phpunit
License
This bundle is released under the MIT license.