RetailCRM-Mirror/NelmioApiDocBundle
1
0
Fork 0
mirror of https://github.com/retailcrm/NelmioApiDocBundle.git synced 2025-04-01 21:06:15 +03:00
Code Issues Projects Releases Wiki Activity

Various documentation enhancements (#1423)

Browse source
This commit is contained in:
Quentin Stoeckel 2018-10-31 16:33:06 +01:00 • committed by Guilhem N
parent 48aaca92e3
commit 6c6a04bba7
3 changed files with 8 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
Resources/doc/alternative_names.rst
View file

@ -1,13 +1,13 @@
Alternative Names
=================
NelmioApiDoc generates automatically the model names but the ``nelmio_api_doc.models.names`` option allows to
NelmioApiDoc automatically generates the model names but the ``nelmio_api_doc.models.names`` option allows to
customize the names for some models.
Configuration
-------------
You can define alternative names for each group and area combination, the last matching rule is used:
You can define alternative names for each group and area combinations: when conflicts arises, the last matching rule will be used:
.. code-block:: yaml

2
Resources/doc/faq.rst
View file

@ -4,7 +4,7 @@ Frequently Asked Questions (FAQ)
Sharing parameter configuration
-------------------------------
Q: I use the same value in multiple end points. How can I avoid duplicating the descriptions?
Q: I use the same value in multiple endpoints. How can I avoid duplicating the descriptions?
A: You can configure ``definitions`` in the nelmio_api_doc configuration and then reference them:

11
Resources/doc/index.rst
View file

@ -2,7 +2,7 @@ NelmioApiDocBundle
==================
The **NelmioApiDocBundle** bundle allows you to generate documentation in the
OpenAPI (Swagger) format and provides a sandbox to interactively browse the API documentation.
OpenAPI (Swagger) format and provides a sandbox to interactively experiment with the API.
What's supported?
-----------------
@ -88,7 +88,7 @@ Open a command console, enter your project directory and execute the following c
How does this bundle work?
--------------------------
It generates you an OpenAPI documentation from your symfony app thanks to
It generates an OpenAPI documentation from your Symfony app thanks to
**Describers**. One extracts data from SwaggerPHP annotations, one from your
routes, etc.
@ -99,8 +99,7 @@ Using the bundle
----------------
You can configure global information in the bundle configuration ``documentation.info`` section (take a look at
`the OpenAPI 2.0 specification (formerly Swagger)`_ to know the fields
available):
`the OpenAPI 2.0 specification (formerly Swagger)`_ to know the available fields):
.. code-block:: yaml
@ -170,7 +169,7 @@ To document your routes, you can use the SwaggerPHP annotations and the
}
}
The normal PHP docblock for the controller method is used for the summary and description.
The normal PHPdoc block on the controller method is used for the summary and description.
Use models
----------
@ -265,7 +264,7 @@ General PHP objects
When using the JMS serializer combined with `willdurand/Hateoas`_ (and the `BazingaHateoasBundle`_),
HATEOAS metadata are automatically extracted
If you want to customize the documentation of a property of an object, you can use ``@SWG\Property``::
If you want to customize the documentation of an object's property, you can use ``@SWG\Property``::
use Nelmio\ApiDocBundle\Annotation\Model;
use Swagger\Annotations as SWG;