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!

It's a pretty hard to document my API. I think we need more examples with PHP Attributes. In my case I don't know how to describe an input Dto with array parameters, described at another Dto.

I tried to use Property type array, but it is marked as "deprecated" and not clear what I should to use instead:

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

class CreateRefundDto
{

#[OA\Property(
    description: 'Refund rows',
    type: ̶a̶r̶r̶a̶y̶,
    items: new OA\Items(
        ref: new NOA\Model(
            type: CreateRefundRowDto::class
        ),
    ),
)]

When I change type "array" to something else I've got an error: User Warning: @OA\Items() parent type must be "array" in \App\Core\DataEntity\RefundInput->rows in

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.

My src/Model/Custom/Modules.php

The extends Model class has golbalScope.

<?php

namespace App\Model\Miggroup;

use Illuminate\Database\Eloquent\Model;

class Modules extends Model
{
}

my nelmio...yml:

  areas: # to filter documented areas
    default:
      disable_default_routes: true
      documentation:
        tags:
          - name: "default"
      path_patterns:
        - ^/(?!/doc$) 
    internal:
      documentation:
        tags:
          - name: "Tag1"
      path_patterns:
        - ^/modules(?!/doc$) 

How can I avoid to disable to parse namespaces or the folder src/Modelin Nelmio?

It would be great that the documentation might get an update.

    When you install JMS serializer, the bundle is automatically configured to use it.

Have you tried adding in your config:

nelmio_api_doc:
    models: { use_jms: false }

? (from the documentation: https://symfony.com/bundles/NelmioApiDocBundle/current/index.html#general-php-objects)

Originally posted by @GuilhemN in https://github.com/nelmio/NelmioApiDocBundle/issues/1886#issuecomment-941089881

@GuilhemN,

Be able to configure a serializer for a method in a controller, or even for the entire controller class, or for a model. Models are better.

In large projects, migrating from one serializer to another is long and problematic, it would be great to be able to configure this parameter for each model, by default - a common `use_jms' ...

example: @SWG\Schema(ref=@Model(type=Generate\Command::class, options={"use_jms": false}, groups={"default"}))

Best solution - jms to symfony annotation/attributes conveter 😂

Hello, I installed NelmioApiDocBundle for a Symfony project. Then the generated swagger needs to be imported in API Manager. Is there a way to auto-generate the x-auth-type attribute used by API Manager? Thanks.