Generated Swagger spec enhancements

[mastersilv3r]

The Problem

Currently the swagger spec generated from events does not create tags & operationid keys. Because of no tags the Swagger UI doesn't bring organised APIs. Because of no operationId, it is difficult to generate client for a swagger spec.

The Solution

Generate Swagger UI with tags and operationId

How to solve

• For tags: either developer gives tags array in schema of event or calculate it from the id of the file. If none of this is present, then use ${method}_${endpoint} remove / from endpoint

• For operationId: developer can give operationId, or id in the event shema. If none of this is present, then use the summary of the event to generate the id

In yamlLoader.ts add tags in every event

const eventFileId = file
      .replace(new RegExp(`.*?\/${basePath}\/`), '')
      .replace(/\//g, '.')
      .replace(/\.(yaml|yml)/i, '')
      .replace(/\.index$/, '');
    
  if (basePath === 'events') {
      for (let eventKey of Object.keys(module)) {
        module[eventKey].tags = module[eventKey].tags || [eventFileId];
      }
    }

In core/router/Swagger.ts

//For every event calculate operationId and tags
    apiEndPoint = apiEndPoint.replace(/:([^\/]+)/g, '{$1}'); //In Godspeed we take :path_param. OAS3 takes {path_param}


// Add in every event schema

tags: [
        eventSchema.tags
      ],
           operationId: eventSchema.operationId || eventSchema.id || eventSchema.summary?.replace(' ', '_') || `${method}_${apiEndPoint}`.replace(/\//g, '_'),

Test Cases

Generated Swagger should have endpoints like this..

"paths": {
        "/lending_service_db/loanapplication/{id}": {
            "get": {
                "summary": "Fetch LoanApplication",
                "description": "Fetch LoanApplication from database",
                "tags": [
                    
                        "lending_service_db.loanapplication"
                    
                ],
                "operationId": "Fetch_LoanApplication",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
    ....

UI will look like this