mirror of
https://github.com/retailcrm/NelmioApiDocBundle.git
synced 2025-04-08 11:42:07 +00:00
Generates documentation for your REST API from annotations
da02f3ad33
* Return a Result Object from AnnotationsReader::updateDefinition
This is so we can make a decision on whether or not a schema's type or
ref has been manually defined by a user via an `@OA\Schema` annotation
as something other than an object.
If it has been defined, this bundle should not read model properties any
further as it causes errors.
I put this in AnnotationReader as it seemed the most flexible in the
long run. It could have gone in `OpenApiAnnotationsReader`, but then any
additional things added to `updateDefinition` could be left out of the
decision down the road. This is also a convenient place to decide this
once for `ObjectModelDescriber` and `JMSModelDescriber`.
* Stop Model Describer if a Schema Type or Ref Has Been Defined
Via the result object added in the previous commit.
This lets user "short circuit" the model describers by manually defining
the schema type or ref on a plain PHP object or form. For example,
a collection class could be defined like this:
/**
* @OA\Schema(type="array", @OA\Items(ref=@Model(type=SomeEntity::class)))
*/
class SomeCollection implements \IteratorAggregate { }
Previously the model describer would error as it tries to merge the
`array` schema with the already defiend `object` schema. Now it will
prefer the array schema and skip reading all the properties of the
object.
* Add a Documentation Bit on Stopping Property Description
* Mark UpdateClassDefinitionResult as Internal
|
||
|---|---|---|
| .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.