Hello,

I recently contacted @willdurand for a plan about the future of this Bundle, as some of you have may have read / heard that he does not wish to maintain this libray anymore.

In this text, he speaks about Swagger v2, which, i totally agree, is now close to be a defacto standard for REST API specification and documentation.

However NelmioApiDocBundle give a very easy path for developers to expose their API documentation by just writing the server part, which brings many benefits: less maintenance, pure synchronisation between doc and code and support a large variety of API "builders" (jms, dunglas api bundle, fos rest).

Given those facts, the goal would be to keep the current easy and synchronized way of doing, but refactoring the "view" part to only expose an OpenAPI specification (new name of Swagger).

All this work will be release in a v3, we will also use this version to reduce the scope of dependencies: There will be support for Symfony >= 2.8 and PHP >= 5.5.9 (same version supported by Symfony 3.X).

There will still be work on the 2.X branch of NelmioApiDocBundle, however it will be restricted to bugs fixes at the condition it doesn't involve too many changes (it would certainly not be done if it implies to refactor too many things in order to be fix, unless there is a good PR).

Before going into this direction we would like to hear from you (people using this bundle) if you think or don't think it's a good way to improve this library.

A proposal to support the GroupsExclusionStrategy of the JMS Serializer.

From the updated readme in this PR:

When using a class with JMS Serializer metadata, you can use exclude groups by using this syntax: input="Acme\YourBundle\Entity\User@update,public". In this case the groups 'update' and 'public' are used.

This implements a new feature called Section Grouping, discussed on issue #25.

The solution is quite simple, and could be reviewed to later refactoring.

All you have to do is declare the same section property to two or more actions, and they will be displayed grouped, just the way resources are.

This has precedence over the resource, but that can be easily changed.

The default section is 'none'.

PS Tests are failing because of the datetime handler for the JMSSerializerBundle, as discussed in #106.

This PR fix deprecated routing config throwing related errors:

The "pattern" is deprecated since version 2.2 and will be removed in 3.0. Use the "path" option in the route definition instead.

The "_method" requirement is deprecated since version 2.2 and will be removed in 3.0. Use the setMethods() method instead or the "methods" option in the route definition.

The "_scheme" requirement is deprecated since version 2.2 and will be removed in 3.0. Use the setSchemes() method instead or the "schemes" option in the route definition.

We have to bump symfony/framework-bundle to ~2.2 version. Not a big deal because 2.1 is not maintained anymore.

I want to use api key or jwt in later, but for now I just want /api/doc to use

  @Security("is_granted('IS_AUTHENTICATED_FULLY')")

I tried to run ./bin/console debug:config NelmioApiDocBundle

But all it lists is the basic config, where are the rest of the options?

This PR adds support for OpenApi 3 and drops Swagger 2. I was inspired by Util class created by @calbrecht & initial try at OA3 support made by @namoscato in this PR: #1555

After I failed with picking up work, where @namoscato ended in his PR & also merging nelmo master branch into that namoscatos OA3 branch, I decided to start over from current master branch.

All tests are green. And this branch should generate valid OpenApi 3 specs.

if this PR is merged, that it should be also new Major Version as it completely changes the bundle output.

Even though this update can generate OA3 and pipeline should be green, there are still few tweaks, that I want to implement, before it can be merged.

I'll dig into those this weekend or next week. In the meantime, if you could give me any feedback, what else should I improve so it can be released. I would appreciate it really a lot :)

Hey all,

this is a PR. It's currently WIP, so, Tests are not added, and not all templates are up to date. I wanted to get some feedback first (and whether there is any interest for that). Basically it adds two new parameters to the ApiDoc annotation. I updated the README to show how to use them.

I noticed that "response" was just merged in, however I believe that my response codes is different. Any feedback is appreciated.

Hello,

our company has been using NelmioApiDocBundle 2.x and now we would like to move to Swagger/OAS and so we were experimenting upgrading to 3.x. However, we found out that the library used to build the apidoc output ("exsyst/swagger") only supports OAS 2.x but we would prefer to go straight to OAS 3.x so that there is no redundant work if we want to teach our client code to parse our APIs.

Are there any plans to add support for OAS 3.x in the near future or at all? Thank you!

My API returns a list of objects. The annotation is as follows:

@ApiDoc(
description="Retrieves all SI Prefixes in the database",
output="PartKeepr\SiPrefixBundle\Entity\SiPrefix"
 )

This works fine, however, it doesn't indicate that PartKeepr\SiPrefixBundle\Entity\SiPrefix is an array. I could, of course, add a collection, but simply putting up a separate collection with proper type hints leads to lots of duplication. I would have expected to specify the output as JMSType specification, e.g. something like this:

@ApiDoc(
description="Retrieves all SI Prefixes in the database",
output="ArrayCollection<PartKeepr\SiPrefixBundle\Entity\SiPrefix>"
 )

However, this doesn't work. Is there any other way to specify that a collection is returned?

It seems that entity properties that have validations have their JMS serialization group ignored when filtered in the output parameter.

For example, here's a property in my entity

    /**
     * @ORM\Column(type="integer")
     * @ORM\Id
     * @ORM\GeneratedValue(strategy="AUTO")
     * @Serializer\Expose
     * @Serializer\Since("1.0")
     * @Serializer\Groups({"userDetails", "userList"})
     */
    protected $id;

    /**
     * @ORM\Column(type="string", length=25, unique=true)
     * @Serializer\Expose
     * @Serializer\Since("1.0")
     * @Serializer\Groups({"userDetails", "userList"})
     */
    protected $username;

    /**
     * @ORM\Column(type="string", length=60, unique=true)
     * @Serializer\Expose
     * @Serializer\Since("1.0")
     * @Serializer\Groups({"userDetails"})
     */
    private $email;

In my controller's ApiDoc annotation, I have

    * ...
     * output={
     *      "class"="Acme\UserBundle\Entity\User",
     *      "groups"={"userList"}
     *   }
     *  ...

In the docs, email still shows up because I have in my loadValidatorMetadata function

$metadata->addPropertyConstraint('email',     new Assert\Email(
            array(
                'message' => 'Email invalid,
                'groups'  => array('SecondPass')
            )
        ));

        $metadata->addConstraint(new UniqueEntity(
            array(
                'fields'           => array('email'),
                'message'          => 'Email invalid',
                'repositoryMethod' => 'checkUniqueUsernameEmail'
            )
        ));

So....any suggestions on how I can get the api doc to not include the properties that match this scenario?

Thanks, Alan

Hi all!

When I add a filter which can hold a list of ids ([1, 45, 343, 4345, 914234]) I cannot enter that list in sandbox mode.

Filter promotorIds

    /**
     * Some method documentation.......
     *
     * @ApiDoc(
     *  resource=true,
     *  description="Load list of events",
     *  statusCodes={
     *      200="Returned when successful",
     *      400="Bad user input",
     *      500="In case of server error, our bad!"
     *  }
     * )
     *
     * @param ParamFetcher $paramFetcher
     *
     * @QueryParam(array=true, name="promotorIds", requirements="\d+", strict=true, description="Array with promotor IDs", nullable=true)
     *
     * @return array response data
     */
    public function getEventsAction(ParamFetcherInterface $paramFetcher)

The sandbox mode

I expected a way to add one or multiple promotor ids. Now I see a single input field in which I cannot specify a list of promotor ids. When I want to test my API method I manually have to write the URL /events.json?promotorIds[]=1&promotorIds[]=2&offset=0&limit=100

See https://github.com/nelmio/NelmioApiDocBundle/blob/master/Resources/views/method.html.twig#L219

How are you guys dealing with this?

Many thanks for your time!

Hi,

When I upgraded the doctrine/doctrine-bundle from 2.7 to 2.8, the NelmioApiDocBundle stopped to work:

    The service "nelmio_api_doc.model_describers.object" has a dependency on a
    non-existent service "annotations.reader".

Looks like the doctrine/doctrine-bundle moved their dependency on doctrine/annotations from the required to require-dev section, starting from version 2.8.0.

Any advice, workaround, or maybe a new version of this great bundle which will work with the recent DoctrineBundle, please? :)

P.S. The NelmioApiDocBundle is great, btw. Thanks!

I'm using the api-doc-bundle 4.10.2 with larger swagger data generated in Symfony, but when I access the api doc and I try expand 2 or more operations the browser is crash.

Follow my configuration:

nelmio_api_doc:
    areas:
        path_patterns: # an array of regexps
        - ^/[a-z]
    documentation:
        components:
            securitySchemes:
                Bearer:
                    type: http
                    scheme: bearer
                    bearerFormat: JWT

Is there a way to paginate the api doc?

Thank you.

Adds an "enum" schema to route parameters if the routing requirements consists only of a simple OR regex epression. It skips complex expression. The schema "pattern" field still contains the original regex. This is mainly useful to display enum values in the Swagger UI gui as select boxes rather than text boxes.

This commit (https://github.com/nelmio/NelmioApiDocBundle/commit/181f4b276356f34ea307b5d44ec7ff6cc189ea27) broke functionality of defining servers urls to area, as well you can't specify now custom server_url, its only taken from request parameters and can't be rewrited.

1. First issue is that if you specify servers for area it is rewrited by: https://github.com/arturssmirnovs/NelmioApiDocBundle/blob/master/Render/RenderOpenApi.php#L77

2. Second issue is that you can't specify custom server_url for default area. As its taken from: https://github.com/arturssmirnovs/NelmioApiDocBundle/blob/master/Render/RenderOpenApi.php#L54

Real word scenario for second issue is when you have HTTPS connection managed by Cloudflare or some loadbalancer & end system gets 80 port request, doc generates links as http, but it would be nice to force overwrite them with server_url to https.

My use case is I have an entity which has a nullable string ?string property (so the deserialization will work, since null can be passed) but the validation will check that it is not null, in which case I know that it will always be a string

Without this change, even tough I have @OA\Property(nullable=false) set in the entity, it gets ignored... this change fixes this and it will show up correctly as nullable: false in swagger docs

Made a small change after the fact, it checks if nullable is not undefined, and if it's false it will mark it undefined, so they don't show up as nullable: false for all the properties in the doc which is not necessary