Adding authentication documentation to Swagger in NelmioApiDocBundle

user_8776129 0
Viewed 604

I'm using Symfony (5) with NelmioApiDocBundle (4.0) and LexikJWTAuthenticationBundle to create an API with Swagger. I've set up endpoints and authentication and everything is working as expected. I have fully functional API with authentication, there is a documentation and I can successfully generate Open API spec. There is one thing missing in specification: "Authentication endpoint" and I can`t find a way to add it to generated specification and documentation (except overwriting the whole authentication)

Because I'm using Symfony security layer and firewalls and it`s integrated with LexikJWTAuthenticationBundle there is no place to set Swagger annotations and it seems like bundle itself doesn't handle generating a "security part" Some time ago I worked with an ApiPlatform and over there it is done by a "decorator"

Anyone knows is there a way (annotations?) to generate security part of the documentation or do I have to create authentication guard from the scratch (?)

lexikjwtauthbundle nelmioapidocbundle symfony swagger authentication
1 Answers

Nevermind. Minute i posted it i found a solution. In a packages/nelmio_bundle_api.yaml you can configure additional documentation (swagger specification) that is not created by annotations. Basically you have to add a new path that is poiting to your authenticatio route (in my case /api/login_check) and define Credential and Token objects in "component" section.

So with symfony authorization it would be (this is just a security part of yaml file):

nelmio_api_doc:
    documentation:
        paths:
            /api/login_check:
                post:
                    tags:
                        - Token
                    operationId: postCredentialsItem
                    summary: Get JWT token to login.
                    requestBody:
                        description: Create new JWT Token
                        content:
                            application/json:
                                schema:
                                    $ref: '#/components/schemas/Credentials'
                    responses:
                        '200':
                            description: Get JWT token
                            content:
                                application/json:
                                    schema:
                                        $ref: '#/components/schemas/Token'
    components:
        schemas:
            Token:
                type: object
                properties:
                    token:
                        type: string
                        readOnly: true
            Credentials:
                type: object
                properties:
                    username:
                        type: string
                    password:
                        type: string
        securitySchemes:
            bearerAuth:            
                type: apiKey
                scheme: bearer
                bearerFormat: JWT   
    security:
        - bearerAuth: []
user_87761290
Related