Nelmioapidocbundle: Document third-party routes

[BraisGabin]

I want to document the FOSOAuthServerBundle's /oauth/v2/token route. The main problem is that being a third code I can not modify it.

I imagine that this functionality is not yet implemented, doesn't it? How should it be addressed? Something like Overriding Third-Party Metadata at JMSSerializerBundle?

[willdurand]

Well, I could add documentation to the FOSOAuthServerBundle I guess..

[KeKs0r]

Is there a possibility to do this in the meantime? Or was documentation added to FOSOauthServer Bundle?

[defrag]

I would like that feature to document third party routes as well. Is there a way to do it?

[AlmogBaku]

@willdurand documenting it on the 3rd party won't help, cause the annotation parser will fail if this bundle not exists.
Please reopen.

[AlmogBaku]

Is it possible to reopen this? @willdurand

[petrica]

Have a look at this "issue": https://github.com/nelmio/NelmioApiDocBundle/issues/806

Is an alternative to add API documentation using an YML.

[florianajir]

for those who still searching how to add api doc for oauth routes here is a working example:

nelmio_api_doc:
    documentation:
        host: '%env(APP_URL)%'
        schemes: [http, https]
        info:
            title: MY SUPER API
            description: My official API
            version: 1.0.0
        securityDefinitions:
            Bearer:
                type: apiKey
                description: 'Value: Bearer {jwt}'
                name: Authorization
                in: header
        security:
            - Bearer: []
        paths:
            /oauth/v2/token:
                get:
                    tags:
                      - oauth
                    description: Login into the api.
                    security: []
                    produces:
                        - application/json
                    parameters:
                        - name: client_id
                          description: Client public token
                          in: query
                          type: string
                          required: true
                        - name: client_secret
                          description: Client secret token
                          in: query
                          type: string
                          required: true
                        - name: grant_type
                          in: query
                          type: string
                          required: true
                          default: client_credentials
                    responses:
                        '200':
                            description: Login successful
                            schema:
                                type: object
                                properties:
                                    access_token:
                                        type: string
                                        example: ODhkOTNlNzA4MDVjNGY2ODE4ZDE1ZjNkNjU4OGE0MzZjYmJmNWM3NmMzMzNlMTNmNzRlNTcxOWUzMTIyZTM0Ng
                                    expires_in:
                                        type: integer
                                        format: int32
                                        example: 3600
                                    token_type:
                                        type: string
                                        example: bearer
                                    scope:
                                        type: string
                                        example: null
                        '400':
                            description: Login error
                            schema:
                                type: object
                                properties:
                                    error:
                                        type: string
                                        example: invalid_client
                                    error_description:
                                        type: string
                                        example: The client credentials are invalid
                post:
                    tags:
                      - oauth
                    description: Login into the api.
                    security: []
                    consumes:
                        - application/x-www-form-urlencoded
                    produces:
                        - application/json
                    parameters:
                        - name: client_id
                          description: Client public token
                          in: formData
                          type: string
                          required: true
                        - name: client_secret
                          description: Client secret token
                          in: formData
                          type: string
                          required: true
                        - name: grant_type
                          in: formData
                          required: true
                          type: string
                          default: client_credentials
                    responses:
                        '200':
                            description: Login successful
                            schema:
                                type: object
                                properties:
                                    access_token:
                                        type: string
                                        example: ODhkOTNlNzA4MDVjNGY2ODE4ZDE1ZjNkNjU4OGE0MzZjYmJmNWM3NmMzMzNlMTNmNzRlNTcxOWUzMTIyZTM0Ng
                                    expires_in:
                                        type: integer
                                        format: int32
                                        example: 3600
                                    token_type:
                                        type: string
                                        example: bearer
                                    scope:
                                        type: string
                                        example: null
                        '400':
                            description: Login error
                            schema:
                                type: object
                                properties:
                                    error:
                                        type: string
                                        example: invalid_client
                                    error_description:
                                        type: string
                                        example: The client credentials are invalid
    routes:
        path_patterns:
            - ^/api(?!/doc$) # Accepts routes under /api except /api/doc
            - ^/oauth