Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add tip to install twig and assets packages. #2051

Merged
merged 4 commits into from
Nov 13, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 19 additions & 15 deletions Resources/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,10 @@ By default, only routes under ``/api`` are documented. Update the regexp at ``ne
host_patterns: # document only routes with a host of the form api.*
- ^api\.

.. tip::

`Twig <https://symfony.com/components/Twig%20Bundle>`_ and `Assets <https://symfony.com/components/asset>`_ packages are needed to use swagger ui.

How does this bundle work?
--------------------------

Expand All @@ -103,7 +107,7 @@ Using the bundle
----------------

You can configure global information in the bundle configuration ``documentation.info`` section (take a look at
`the OpenAPI 3.0 specification (formerly Swagger)`_ to know the available fields).
`the OpenAPI 3.0 specification (formerly Swagger)`_ to know the available fields).

.. code-block:: yaml

Expand Down Expand Up @@ -135,16 +139,16 @@ You can configure global information in the bundle configuration ``documentation

.. tip::

This configuration field can more generally be used to store your documentation as yaml.
You may find in the ``.yaml`` files from `SwaggerPHP examples`_.
This configuration field can more generally be used to store your documentation as yaml.
You may find in the ``.yaml`` files from `SwaggerPHP examples`_.

To document your routes, you can use the SwaggerPHP annotations and the
``Nelmio\ApiDocBundle\Annotation\Model`` annotation in your controllers::

.. configuration-block::

.. code-block:: php-annotations

namespace AppBundle\Controller;

use AppBundle\Entity\Reward;
Expand Down Expand Up @@ -184,9 +188,9 @@ To document your routes, you can use the SwaggerPHP annotations and the
// ...
}
}

.. code-block:: php-attributes

namespace AppBundle\Controller;

use AppBundle\Entity\Reward;
Expand All @@ -208,7 +212,7 @@ To document your routes, you can use the SwaggerPHP annotations and the
response: 200,
description: 'Returns the rewards of an user',
content: new OA\JsonContent(
type: 'array',
type: 'array',
items: new OA\Items(ref: new Model(type: AlbumDto::class, groups: ['full']))
)
)]
Expand All @@ -225,15 +229,15 @@ To document your routes, you can use the SwaggerPHP annotations and the
// ...
}
}


The normal PHPDoc block on the controller method is used for the summary and description.

.. tip::

Examples of using the annotations can be found in `SwaggerPHP examples`_.
However, unlike in those examples, when using this bundle you don't need to specify paths and you can easily document models as well as some
other properties described below as they can be automatically be documented using the Symfony integration.
other properties described below as they can be automatically be documented using the Symfony integration.

Use Models
----------
Expand All @@ -252,7 +256,7 @@ This annotation has two options:
.. configuration-block::

.. code-block:: php-annotations

/**
* @OA\Response(
* response=200,
Expand Down Expand Up @@ -283,7 +287,7 @@ This annotation has two options:
*/

.. code-block:: php-attributes

#[OA\Response(
response: 200,
description: 'Successful response',
Expand Down Expand Up @@ -449,9 +453,9 @@ General PHP objects
**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.

NOTE: If you are using serialization contexts (e.g. Groups) each permutation will be treated as a separate Path. For example if you have the following two variations defined in different places in your code:

.. code-block:: php

/**
Expand Down Expand Up @@ -499,7 +503,7 @@ If you want to customize the documentation of an object's property, you can use
.. configuration-block::

.. code-block:: php-annotations

use Nelmio\ApiDocBundle\Annotation\Model;
use OpenApi\Annotations as OA;

Expand Down Expand Up @@ -530,7 +534,7 @@ If you want to customize the documentation of an object's property, you can use
}

.. code-block:: php-attributes

use Nelmio\ApiDocBundle\Annotation\Model;
use OpenApi\Attributes as OA;

Expand Down