Merge pull request #1171 from nelmio/docs

Rework the docs
2025-02-09 02:59:27 +03:00 · 2018-01-04 20:08:06 +01:00 · 2018-01-04 20:08:06 +01:00 · 92f3eb633b
commit 92f3eb633b
parent 447f44e5a1 108687ec8e
3 changed files with 248 additions and 152 deletions
--- a/README.md
+++ b/README.md
@ -2,7 +2,7 @@ NelmioApiDocBundle
 ==================
 [![Build
-Status](https://secure.travis-ci.org/nelmio/NelmioApiDocBundle.png?branch=master)](http://travis-ci.org/nelmio/NelmioApiDocBundle)
+Status](https://travis-ci.org/nelmio/NelmioApiDocBundle.svg?branch=master)](http://travis-ci.org/nelmio/NelmioApiDocBundle)
 [![Total Downloads](https://poser.pugx.org/nelmio/api-doc-bundle/downloads)](https://packagist.org/packages/nelmio/api-doc-bundle)
 [![Latest Stable
 Version](https://poser.pugx.org/nelmio/api-doc-bundle/v/stable)](https://packagist.org/packages/nelmio/api-doc-bundle)
@ -16,161 +16,15 @@ for your APIs.
 ## Installation
-First, open a command console, enter your project directory and execute the following command to download the latest version of this bundle:
+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 dev-master
+composer require nelmio/api-doc-bundle
 ```
-Then add the bundle to your kernel:
+## Documentation
 ```php
 class AppKernel extends Kernel
 {
    public function registerBundles()
    {
        $bundles = [
            // ...
-            new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
+[Read the documentation on symfony.com](https://symfony.com/doc/current/bundles/NelmioApiDocBundle/index.html)
        ];
        // ...
    }
 }
 ```
 To browse your documentation with Swagger UI, register the following route:
 ```yml
 # app/config/routing.yml
 app.swagger_ui:
    resource: "@NelmioApiDocBundle/Resources/config/routing/swaggerui.xml"
    prefix:   /api/doc
 ```
 If you also want to expose it in JSON, register this route:
 ```yml
 # app/config/routing.yml
 app.swagger:
    path: /api/doc.json
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.swagger }
 ```
 ## What does this bundle?
 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
 routes, etc.
 If you configured the ``app.swagger_ui`` route above, you can browse your
 documentation at `http://example.org/api/doc`.
 ## Configure the bundle
 As you just installed the bundle, you'll likely see routes you don't want in
 your documentation such as `/_profiler/`. To fix this, you can filter the
 routes that are documented by configuring the bundle:
 ```yml
 # app/config/config.yml
 nelmio_api_doc:
    routes:
        path_patterns: # an array of regexps
            - ^/api
 ```
 ## Use the bundle
 You can configure globally your documentation in the config (take a look at
 [the Swagger specification](http://swagger.io/specification/) to know the fields
 available):
 ```yml
 nelmio_api_doc:
    documentation:
        info:
            title: My App
            description: This is an awesome app!
            version: 1.0.0
 ```
 To document your routes, you can use annotations in your controllers:
 ```php
 namespace AppBundle\Controller;
 use AppBundle\Entity\User;
 use AppBundle\Entity\Reward;
 use Nelmio\ApiDocBundle\Annotation\Model;
 use Swagger\Annotations as SWG;
 use Symfony\Component\Routing\Annotation\Route;
 class UserController
 {
    /*
     * @Route("/api/{user}/rewards", methods={"GET"})
     * @SWG\Response(
     *     response=200,
     *     description="Returns the rewards of an user",
     *     @SWG\Schema(
     *         type="array",
     *         @Model(type=Reward::class, groups={"full"})
     *     )
     * )
     * @SWG\Parameter(
     *     name="order",
     *     in="query",
     *     type="string",
     *     description="The field used to order rewards"
     * )
     * @SWG\Tag(name="rewards")
     */
    public function fetchUserRewardsAction(User $user)
    {
        // ...
    }
 }
 ```
 ## Use models
 As shown in the example above, the bundle provides the ``@Model`` annotation.
 When you use it, the bundle will deduce your model properties.
 ### If you're not using the JMS Serializer
 The [Symfony PropertyInfo component](https://symfony.com/doc/current/components/property_info.html)
 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](https://symfony.com/doc/current/components/property_info.html) (you
 won't be able to use JMS serialization groups), you can disable JMS serializer
 support in your config:
 ```yml
 nelmio_api_doc:
    models: { use_jms: false }
 ```
 ## What's supported?
 This bundle supports _Symfony_ route requirements, PHP annotations,
 [_Swagger-Php_](https://github.com/zircote/swagger-php) annotations,
 [_FOSRestBundle_](https://github.com/FriendsOfSymfony/FOSRestBundle) annotations
 and apps using [_Api-Platform_](https://github.com/api-platform/api-platform).
 For models, it supports the Symfony serializer and the JMS serializer.
 ## Contributing
--- a/Resources/doc/index.rst
+++ b/Resources/doc/index.rst
@ -0,0 +1,242 @@
 NelmioApiDocBundle
 ==================
 The **NelmioApiDocBundle** bundle allows you to generate documentation in the
 OpenAPI (Swagger) format and provides a sandbox to interactively browse the API documentation.
 What's supported?
 -----------------
 This bundle supports _Symfony_ route requirements, PHP annotations,
 [_Swagger-Php_](https://github.com/zircote/swagger-php) annotations,
 [_FOSRestBundle_](https://github.com/FriendsOfSymfony/FOSRestBundle) annotations
 and apps using [_Api-Platform_](https://github.com/api-platform/api-platform).
 For models, it supports the Symfony serializer and the JMS serializer.
 Migrate from 2.x to 3.0
 -----------------------
 [To migrate from 2.x to 3.0, just follow our guide.](https://github.com/nelmio/NelmioApiDocBundle/blob/master/UPGRADE-3.0.md)
 Installation
 ------------
 Open a command console, enter your project directory and execute the following command to download the latest version of this bundle:
 .. code-block:: bash
    $ composer require nelmio/api-doc-bundle
 .. note::
    If you're not using Flex, then add the bundle to your kernel::
        class AppKernel extends Kernel
        {
            public function registerBundles()
            {
                $bundles = [
                    // ...
                    new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
                ];
                // ...
            }
        }
    To browse your documentation with Swagger UI, register the following route:
    .. code-block:: yaml
        # app/config/routing.yml
        app.swagger_ui:
            path: /api/doc
            methods: GET
            defaults: { _controller: nelmio_api_doc.controller.swagger_ui }
    If you also want to expose it in JSON, register this route:
    .. code-block:: yaml
        # app/config/routing.yml
        app.swagger:
            path: /api/doc.json
            methods: GET
            defaults: { _controller: nelmio_api_doc.controller.swagger }
    As you just installed the bundle, you'll likely see routes you don't want in
    your documentation such as `/_profiler/`. To fix this, you can filter the
    routes that are documented by configuring the bundle:
    .. code-block:: yaml
        # app/config/config.yml
        nelmio_api_doc:
            areas:
                path_patterns: # an array of regexps
                    - ^/api(?!/doc$)
 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
 routes, etc.
 If you configured the ``app.swagger_ui`` route above, you can browse your
 documentation at `http://example.org/api/doc`.
 Using the bundle
 ----------------
 You can configure global information in the bundle configuration ``documentation.info`` section (take a look at
 [the Swagger specification](http://swagger.io/specification/) to know the fields
 available):
 .. code-block:: yaml
    nelmio_api_doc:
        documentation:
            info:
                title: My App
                description: This is an awesome app!
                version: 1.0.0
 .. note::
    If you're using Flex, this config is there by default. Don't forget to adapt it to your app!
 To document your routes, you can use the SwaggerPHP annotations and the
 ``Nelmio\ApiDocBundle\Annotation\Model`` annotation in your controllers::
    namespace AppBundle\Controller;
    use AppBundle\Entity\User;
    use AppBundle\Entity\Reward;
    use Nelmio\ApiDocBundle\Annotation\Model;
    use Swagger\Annotations as SWG;
    use Symfony\Component\Routing\Annotation\Route;
    class UserController
    {
        /*
         * @Route("/api/{user}/rewards", methods={"GET"})
         * @SWG\Response(
         *     response=200,
         *     description="Returns the rewards of an user",
         *     @SWG\Schema(
         *         type="array",
         *         @Model(type=Reward::class, groups={"full"})
         *     )
         * )
         * @SWG\Parameter(
         *     name="order",
         *     in="query",
         *     type="string",
         *     description="The field used to order rewards"
         * )
         * @SWG\Tag(name="rewards")
         */
        public function fetchUserRewardsAction(User $user)
        {
            // ...
        }
    }
 Use models
 ----------
 As shown in the example above, the bundle provides the ``@Model`` annotation.
 When you use it, the bundle will deduce your model properties.
 It has two options:
 * ``type`` to specify your model's type::
    /**
     * @Model(type=User::class)
     */
 * ``groups`` to specify the serialization groups used to (de)serialize your model::
    /**
     * @Model(type=User::class, groups={"non_sensitive_data"})
     */
 .. warning::
    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.
    For instance, the following example::
        /**
         * @SWG\Response(
         *   response="200",
         *   description="Success",
         *   @SWG\Schema(@Model(type=User::class))
         * )
         */
        public function getUserAction()
        {
        }
    will produce:
    .. code-block:: yaml
        # ...
        responses:
            200:
                schema:
                    items: { $ref: '#/definitions/MyModel' }
    while you probably expected:
    .. code-block:: yaml
        # ...
        responses:
            200:
                schema: { $ref: '#/definitions/MyModel' }
    To obtain the output you expected, remove the ``@Schema`` annotation::
        /**
         * @SWG\Response(
         *   response="200",
         *   description="Success",
         *   @Model(type=MyModel::class)
         * )
         */
        public function myAction()
        {
        }
 If you're not using the JMS Serializer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The [Symfony PropertyInfo component](https://symfony.com/doc/current/components/property_info.html)
 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](https://symfony.com/doc/current/components/property_info.html) (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 }
--- a/Tests/DependencyInjection/NelmioApiDocExtensionTest.php
+++ b/Tests/DependencyInjection/NelmioApiDocExtensionTest.php
@ -9,7 +9,7 @@
 * file that was distributed with this source code.
 */
-namespace Nelmio\ApiDocBundle\Tests\Describer;
+namespace Nelmio\ApiDocBundle\Tests\DependencyInjection;
 use Nelmio\ApiDocBundle\DependencyInjection\NelmioApiDocExtension;
 use PHPUnit\Framework\TestCase;