The NelmioApiDocBundle bundle allows you to generate a decent documentation for your APIs

Overview

NelmioApiDocBundle

Build Status Total Downloads Latest Stable Version

The NelmioApiDocBundle bundle allows you to generate a decent documentation for your APIs.

Migrate from 3.x to 4.0

To migrate from 3.x to 4.0, follow our guide.

Version 4.0 brings OpenAPI 3.0 support. If you want to stick to Swagger 2.0, you should use the version 3 of this bundle.

Migrate from 2.x to 3.0

To migrate from 2.x to 3.0, follow our guide.

Installation

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

Documentation

Read the documentation on symfony.com

Contributing

See CONTRIBUTING file.

Running the Tests

Install the Composer dependencies:

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

Then run the test suite:

./phpunit

License

This bundle is released under the MIT license.

Comments
  • [RFC] Future of NelmioApiDocBundle (v3 ?)

    [RFC] Future of NelmioApiDocBundle (v3 ?)

    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.

    opened by joelwurtz 39
  • added support for JMS Serializer GroupsExclusionStrategy

    added support for JMS Serializer GroupsExclusionStrategy

    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.

    opened by fieg 39
  • Section grouping

    Section grouping

    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.

    opened by drgomesp 37
  • Fix deprecated route options

    Fix deprecated route options

    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.

    opened by soullivaneuh 36
  • How do you configure authentication?

    How do you configure authentication?

    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?

    opened by wraycode 31
  • OpenApi 3 Support

    OpenApi 3 Support

    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 :)

    opened by FilipBenco 27
  • WIP: HTTP Response Code and Include File

    WIP: HTTP Response Code and Include File

    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.

    opened by baldurrensch 26
  • Support for OAS 3.0

    Support for OAS 3.0

    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!

    opened by majermi4 25
  • Support for collections to output

    Support for collections to output

    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?

    enhancement 
    opened by Drachenkaetzchen 25
  • Entities with validations ignore JMS serializer groups

    Entities with validations ignore JMS serializer groups

    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

    opened by alanhartless 24
  • Array parameters in sandbox

    Array parameters in sandbox

    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 image

        /**
         * 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 image

    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!

    opened by ivodvb 23
  • Incompatibility with DoctrineBundle v2.8

    Incompatibility with DoctrineBundle v2.8

    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!

    opened by webinarium 0
  • Larger data crashing the browser

    Larger data crashing the browser

    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.

    opened by igordeveloper 0
  • Add enum description to route parameter if possible.

    Add enum description to route parameter if possible.

    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.

    opened by lhausammann 0
  • Unable to specify server_url and servers urls

    Unable to specify server_url and servers urls

    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.

    opened by arturssmirnovs 3
  • Check nullable property has nullable set

    Check nullable property has nullable set

    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

    opened by akalineskou 0
Releases(v4.10.2)
Owner
Nelmio
Nelmio
Ariama Victor (A.K.A. OVAC4U) 106 Dec 25, 2022
Facebook SDK for PHP (v6) - allows you to access the Facebook Platform from your PHP app

Facebook SDK for PHP (v6) This repository contains the open source PHP SDK that allows you to access the Facebook Platform from your PHP app. Installa

null 0 Aug 10, 2022
This bundle provides tools to build a complete GraphQL server in your Symfony App.

OverblogGraphQLBundle This Symfony bundle provides integration of GraphQL using webonyx/graphql-php and GraphQL Relay. It also supports: batching with

Webedia - Overblog 720 Dec 25, 2022
A Symfony bundle that provides #StandWithUkraine banner and has some built-in features to block access to your resource for Russian-speaking users.

StandWithUkraineBundle На русском? Смотри README.ru.md This bundle provides a built-in StandWithUkraine banner for your Symfony application and has so

Victor Bocharsky 10 Nov 12, 2022
A simple way of authenticating your RESTful APIs with API keys using Laravel

ApiGuard This package is no longer maintained This package is no longer maintained as Laravel already has a similar feature built-in since Laravel 5.8

Chris Bautista 691 Nov 29, 2022
API documentation API SCB EASY APP

SCB-API-EASY V3.0 API documentation SIAM COMMERCIAL BANK PUBLIC COMPANY LTD. API SCB Easy V3 endpoint = https://fasteasy.scbeasy.link 1.0. Get balance

SCB API Esay team 2 Sep 28, 2021
The Laravel documentation.

Laravel Documentation You can find the online version of the Laravel documentation at https://laravel.com/docs Contribution Guidelines If you are subm

The Laravel Framework 2.6k Dec 31, 2022
Mink documentation

Mink Documentation This repository contains the documentation for the Mink project. The rendered documentation is hosted at Read the Docs. Contribute

Mink 83 Nov 14, 2022
Pure PHP implementation of GraphQL Server – Symfony Bundle

Symfony GraphQl Bundle This is a bundle based on the pure PHP GraphQL Server implementation This bundle provides you with: Full compatibility with the

null 283 Dec 15, 2022
DataTables bundle for Symfony

Symfony DataTables Bundle This bundle provides convenient integration of the popular DataTables jQuery library for realtime Ajax tables in your Symfon

Omines Internetbureau 199 Jan 3, 2023
GraphQL Bundle for Symfony 2.

Symfony 2 GraphQl Bundle Use Facebook GraphQL with Symfony 2. This library port laravel-graphql. It is based on the PHP implementation here. Installat

Sergey Varibrus 35 Nov 17, 2022
An Unleash bundle for Symfony applications to provide an easy way to use feature flags

Unleash Bundle An Unleash bundle for Symfony applications. This provide an easy way to implement feature flags using Gitlab Feature Flags Feature. Ins

Stogon 7 Oct 20, 2022
Symfony Health Check Bundle Monitoring Project Status

Symfony Health Check Bundle Version Build Status Code Coverage master develop Installation Step 1: Download the Bundle Open a command console, enter y

MacPaw Inc. 27 Jul 7, 2022
Copy of hautelook/alice-bundle v2.9.0

AliceBundle A Symfony bundle to manage fixtures with nelmio/alice and fzaninotto/Faker. The database support is done in FidryAliceDataFixtures. Check

Global4Net Ltd. 3 Sep 10, 2021
A bundle providing routes and glue code between Symfony and a WOPI connector.

WOPI Bundle A Symfony bundle to facilitate the implementation of the WOPI endpoints and protocol. Description The Web Application Open Platform Interf

Champs-Libres 5 Aug 20, 2022
Mediator - CQRS Symfony bundle. Auto Command/Query routing to corresponding handlers.

Installation $ composer require whsv26/mediator Bundle configuration // config/packages/mediator.php return static function (MediatorConfig $config)

Alexander Sv. 6 Aug 31, 2022
Airbrake.io & Errbit integration for Symfony 3/4/5. This bundle plugs the Airbrake API client into Symfony project

AmiAirbrakeBundle Airbrake.io & Errbit integration for Symfony 3/4/5. This bundle plugs the Airbrake API client into Symfony project. Prerequisites Th

Anton Minin 8 May 6, 2022
Symfony bundle for EventSauce (WIP)

Symfony EventSauce (WIP) This bundle provides the basic and extended container configuration of symfony for the EventSauce library. Before using it, I

Andrew Pakula 8 Dec 19, 2022
Symfony bundle integrating server-sent native notifications

Symfony UX Notify Symfony UX Notify is a Symfony bundle integrating server-sent native notifications in Symfony applications using Mercure. It is part

Symfony 6 Dec 15, 2022