tireconnect/api-doc-bundle

Generates documentation for your REST API from annotations

Monday, October 30, 2017
by samart
Repository
2 Watchers
0 Stars
42 Installations

PHP
0 Dependents
0 Suggesters
637 Forks
0 Open issues
46 Versions
20 % Grown

The README.md

NelmioApiDocBundle

, _(*1)

The NelmioApiDocBundle bundle allows you to generate a decent documentation for your APIs., _(*2)

Migrate from 2.x to 3.0

To migrate from 2.x to 3.0, just follow our guide., _(*3)

Installation

First, open a command console, enter your project directory and execute the following command to download the latest version of this bundle (still in beta, for a stable version look here):, _(*4)

composer require nelmio/api-doc-bundle dev-master

Then add the bundle to your kernel:, _(*5)

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = [
            // ...

            new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
        ];

        // ...
    }
}

To browse your documentation with Swagger UI, register the following route:, _(*6)

# 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:, _(*7)

# 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., _(*8)

If you configured the app.swagger_ui route above, you can browse your documentation at http://example.org/api/doc., _(*9)

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:, _(*10)

# 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 to know the fields available):, _(*11)

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:, _(*12)

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., _(*13)

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 as long as you required the phpdocumentor/reflection-docblock library. It does also support serialization groups when using the Symfony serializer., _(*14)

If you're using the JMS Serializer

The metadata of the JMS serializer are used by default to describe your models. Note that PHP doc blocks aren't supported in this case., _(*15)

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:, _(*16)

nelmio_api_doc:
    models: { use_jms: false }

What's supported?

This bundle supports Symfony route requirements, PHP annotations, Swagger-Php annotations, FOSRestBundle annotations and apps using Api-Platform., _(*17)

For models, it supports the Symfony serializer and the JMS serializer., _(*18)

Contributing

See CONTRIBUTING file., _(*19)

Running the Tests

Install the Composer dependencies:, _(*20)

git clone https://github.com/nelmio/NelmioApiDocBundle.git
cd NelmioApiDocBundle
composer update

Then run the test suite:, _(*21)

./phpunit

License

This bundle is released under the MIT license., _(*22)

The Versions

30/10 2017

dev-master

9999999-dev

Generates documentation for your REST API from annotations

symfony-bundle api-doc-bundle

Generates documentation for your REST API from annotations

tireconnect/api-doc-bundle

The README.md

NelmioApiDocBundle

Migrate from 2.x to 3.0

Installation

What does this bundle?

Configure the bundle

Use the bundle

Use models

If you're not using the JMS Serializer

If you're using the JMS Serializer

What's supported?

Contributing

Running the Tests

License

The Versions

dev-master

The Requires

The Development Requires

by Symfony Community

by Nelmio

2.x-dev

The Requires

The Development Requires

by Symfony Community

by Nelmio

2.14.0

The Requires

The Development Requires

by Symfony Community

by Nelmio

dev-test

The Requires

The Development Requires

by Symfony Community

by Nelmio

v3.0.0-BETA4

The Requires

The Development Requires

by Symfony Community

by Nelmio

dev-ui

The Requires

The Development Requires

by Symfony Community

by Nelmio

v3.0.0-BETA3

The Requires

The Development Requires

by Symfony Community

by Nelmio

v3.0.0-BETA2

The Requires

The Development Requires

by Symfony Community

by Nelmio

v3.0.0-BETA1

The Requires

The Development Requires

by Symfony Community

by Nelmio

2.13.2

The Requires

The Development Requires

by Symfony Community

by Nelmio

2.13.1

The Requires

The Development Requires

by Symfony Community

by Nelmio

2.13.0

The Requires

The Development Requires

by Symfony Community

by Nelmio

2.12.0

The Requires