RetailCRM-Mirror/NelmioApiDocBundle
1
0
Fork 0
mirror of https://github.com/retailcrm/NelmioApiDocBundle.git synced 2025-02-02 23:59:26 +03:00
Code Issues Projects Releases Wiki Activity

Document how to customize models documentation (#1237)

Browse Source
This commit is contained in:
Guilhem N 2018-02-20 09:59:00 +01:00 committed by David Buchmann
parent d4b0382fa2
commit 37dfb8ef0d
2 changed files with 101 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
Resources/doc/faq.rst
View File

@ -1,12 +1,60 @@
Frequently Asked Questions (FAQ)
================================
* Q: I use ``@Model`` to document an operation and the bundle understands I want an array of models while I only want one.
Q: How do I fix 404 or 406 HTTP status on NelmioApiDocBundle assets files (css, js, images)?
A: You most likely nested ``@Model`` in a ``@Schema`` annotation. The ``@Model`` annotation acts like a ``@Schema`` annotation, so
when nested, the bundle considers that you're documenting an array of models.
A: Just execute this command to solve it:
For instance, the following example::
/**
* @SWG\Response(
      *   response="200",
      *   description="Success",
* @SWG\Schema(@Model(type=User::class))
* )
*/
public function getUserAction()
{
}
.. code-block:: bash
will produce:
$ bin/console assets:install --symlink
.. code-block:: yaml
# ...
responses:
200:
schema:
                  items: { $ref: '#/definitions/User' }
while you probably expected:
.. code-block:: yaml
# ...
responses:
200:
              schema: { $ref: '#/definitions/User' }
To obtain the output you expected, remove the ``@Schema`` annotation::
/**
* @SWG\Response(
* response="200",
* description="Success",
      *   @Model(type=User::class)
* )
*/
public function getUserAction()
{
}
* Q: How do I fix 404 or 406 HTTP status on NelmioApiDocBundle assets files (css, js, images)?
A: Just execute this command to solve it:
.. code-block:: bash
$ bin/console assets:install --symlink

117
Resources/doc/index.rst
View File

@ -14,7 +14,7 @@ This bundle supports *Symfony* route requirements, PHP annotations, `Swagger-Php
.. _`FOSRestBundle`: https://github.com/FriendsOfSymfony/FOSRestBundle
.. _`Api-Platform`: https://github.com/api-platform/api-platform
For models, it supports the Symfony serializer and the JMS serializer.
For models, it supports the Symfony serializer and the JMS serializer. It does also support Symfony form types.
Migrate from 2.x to 3.0
-----------------------
@ -82,16 +82,11 @@ Open a command console, enter your project directory and execute the following c
path_patterns: # an array of regexps
- ^/api(?!/doc$)
  .. versionadded:: 3.1
       The ``areas`` config option was added in version 3.1. You had to use ``routes`` in 3.0 instead.
How does this bundle work?
--------------------------
It generates you a swagger documentation from your symfony app thanks to
**Describers**. Each of these **Describers** extract infos from various sources.
For instance, one extract data from SwaggerPHP annotations, one from your
It generates you an OpenAPI documentation from your symfony app thanks to
**Describers**. One extracts data from SwaggerPHP annotations, one from your
routes, etc.
If you configured the ``app.swagger_ui`` route above, you can browse your
@ -172,7 +167,7 @@ When you use it, the bundle will deduce your model properties.
   A model can be a Symfony form type, a Doctrine ORM entity or a general PHP object.
It has two options:
This annotation has two options:
* ``type`` to specify your model's type::
@ -192,78 +187,65 @@ It has two options:
    * )
    */
.. caution::
Symfony Form types
~~~~~~~~~~~~~~~~~~
The ``@Model`` annotation acts like a ``@Schema`` annotation. If you nest it with a ``@Schema`` annotation, the bundle will consider that
you're documenting an array of models.
You can customize the documentation of a form field using the ``documentation`` option::
For instance, the following example::
$builder->add('username', TextType::class, [
'documentation' => [
'type' => 'string', // would have been automatically detected in this case
'description' => 'Your username.',
],
]);
/**
* @SWG\Response(
        *   response="200",
        *   description="Success",
* @SWG\Schema(@Model(type=User::class))
* )
*/
public function getUserAction()
{
}
See the `OpenAPI specification`__ to see all the available fields of the ``documentation`` option.
will produce:
__ https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject
General PHP objects
~~~~~~~~~~~~~~~~~~~
.. tip::
**If you're not using the JMS Serializer**, the `Symfony PropertyInfo component`_ is used to describe your models. It supports doctrine annotations, type hints,
and even PHP doc blocks. It does also support serialization groups when using the Symfony serializer.
**If you're using the JMS Serializer**, the metadata of the JMS serializer are used by default to describe your
models. Additional information is extracted from the PHP doc block comment,
but the property types must be specified in the JMS annotations.
In case you prefer using the `Symfony PropertyInfo component`_ (you
won't be able to use JMS serialization groups), you can disable JMS serializer
support in your config:
.. code-block:: yaml
# ...
responses:
200:
schema:
                  items: { $ref: '#/definitions/User' }
nelmio_api_doc:
models: { use_jms: false }
while you probably expected:
If you want to customize the documentation of a property of an object, you can use ``@SWG\Property``::
.. code-block:: yaml
use Swagger\Annotations as SWG;
# ...
responses:
200:
              schema: { $ref: '#/definitions/User' }
To obtain the output you expected, remove the ``@Schema`` annotation::
class User
{
/**
* @var int
* @SWG\Property(description="The unique identifier of the user.")
*/
public $id;
/**
* @SWG\Response(
* response="200",
* description="Success",
        *   @Model(type=User::class)
* )
* @SWG\Property(type="string", maxLength=255)
*/
public function getUserAction()
{
}
public $username;
}
If you're not using the JMS Serializer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See the `OpenAPI specification`__ to see all the available fields of ``@SWG\Property``.
The `Symfony PropertyInfo component`_ is used to describe your models. It supports doctrine annotations, type hints,
and even PHP doc blocks as long as you required the ``phpdocumentor/reflection-docblock`` library. It does also support
serialization groups when using the Symfony serializer.
If you're using the JMS Serializer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The metadata of the JMS serializer are used by default to describe your
models. Additional information is extracted from the PHP doc block comment,
but the property types must be specified in the JMS annotations.
In case you prefer using the `Symfony PropertyInfo component`_ (you
won't be able to use JMS serialization groups), you can disable JMS serializer
support in your config:
.. code-block:: yaml
nelmio_api_doc:
models: { use_jms: false }
__ https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject
Learn more
----------
@ -275,6 +257,5 @@ If you need more complex features, take a look at:
areas
faq
.. _`Symfony PropertyInfo component`: https://symfony.com/doc/current/components/property_info.html
.. _`Symfony PropertyInfo component`: https://symfony.com/doc/current/components/property_info.html