Swagger Generation

Swagger is a tool used for generating interactive documentation of Symphony project functions.

• Symphony-cli's build command symphony-cli sym-build --swagger autogenerates a Swagger folder under sym-engine folder.

  )

• The swagger folder contains function schemas along with an OpenAPI file (formerly Swagger Specification).

  

Function Schemas

Function schemas are generated from RegisterFunc interfaces. For schemas to be properly generated, interfaces have to have the exact interface names. Moreover, they have to be written into functions' ts folders. Imported interfaces will result in empty schema files.

    import { ISymphonyObject, symphony } from "@stechsym/symphony";
    import { TReqDefault, TReqHeaderDefault } from "@stechsym/symphony/dist/src/infrastructure/managers/symphonyObject/symphonyRequest";
    import { TRespDefault, TRespHeaderDefault } from "@stechsym/symphony/dist/src/infrastructure/managers/symphonyObject/symphonyResponse";

    export interface IRequest extends TReqDefault {};
    export interface IRequestHeader extends TReqHeaderDefault {};
    export interface IResponse extends TRespDefault { 
        data?: string, 
        sample?: {
            test1: string,
            test2: boolean
        } 
    };
    export interface IResponseHeader extends TRespHeaderDefault {};

    symphony.registerFunc({
        funcName: "samplefunc", keepBag: false, requireFunc: require,
        func: async (sym: ISymphonyObject<IRequest, IRequestHeader, IResponse, IResponseHeader>): Promise<void> => {
            const respGet = await sym.rest.get({ symConfigKey: "restGetExample" });
            sym.response.body.data = respGet.body as string;
        }
    });

The generated schema from the function above is shown below.

    {
        "definitions": {
            "IRequest": {
            "type": "object",
            "additionalProperties": false,
            "title": "IRequest"
            },
            "IRequestHeader": {
            "type": "object",
            "additionalProperties": false,
            "title": "IRequestHeader"
            },
            "IResponse": {
            "type": "object",
            "properties": {
                "data": {
                "type": "string",
                "title": "IResponse.data"
                },
                "sample": {
                "type": "object",
                "properties": {
                    "test1": {
                    "type": "string",
                    "title": "IResponse.sample.test1"
                    },
                    "test2": {
                    "type": "boolean",
                    "title": "IResponse.sample.test2"
                    }
                },
                "required": [
                    "test1",
                    "test2"
                ],
                "additionalProperties": false,
                "title": "IResponse.sample"
                }
            },
            "additionalProperties": false,
            "title": "IResponse"
            },
            "IResponseHeader": {
            "type": "object",
            "additionalProperties": false,
            "title": "IResponseHeader"
            }
        }
    }

Swagger Specification File (Open API Specification)

The swagger folder also includes an Open API file as swagger.json. This file is produced in a standard format to define the structure and the syntax of SwaggerUI. This file accepts any modifications. Building the project after making changes will update SwaggerUI.

A detailed explaination of this file can be accessed through the link below.

OpenAPI Specification Document

The specification file has a paths object that includes all the available endpoints. Operations available at each endpoint exposed by our API are only GET and POST at the moment. The endpoints can be modified in the desired way. The link below contains a comprehensive example of how endpoints can be used in multiple ways.

Swagger Pet Store Example

Endpoints contain related schemas through references. These references are given via the $ref keyword. A detailed explanation of the $ref keyword can be accessed through the link below.

Specification $ref Keyword

    "/samplefunc": {
        "get": {
            "tags": [],
            "summary": "",
            "description": "",
            "parameters": [],
            "responses": {
                "200": {
                    "description": "successful operation",
                    "schema": {
                        "allOf": [
                            {
                                "$ref": "swaggerAPI/samplefuncSchema.json#/definitions/IRequest"
                            },
                            {
                                "$ref": "swaggerAPI/samplefuncSchema.json#/definitions/IResponse"
                            },
                            {
                                "$ref": "swaggerAPI/samplefuncSchema.json#/definitions/IRequestHeader"
                            },
                            {
                                "$ref": "swaggerAPI/samplefuncSchema.json#/definitions/IResponseHeader"
                            }
                        ]
                    }
                }
            }
        }
    }

Schemas could also be included without using the $ref keyword. In order to access the Open API file that contains schemas without references, the build command should be run with the -i parameter (symphony-cli sym-build --swagger -i). This command will result in an extra specification file (swaggerSchemaInclusive.json) without interfering with the usual usage of the existing SwaggerUI.

Accessing Open API and SwaggerUI

After the project build is completed, the run command symphony-cli sym-start will generate two extra URLs.

SwaggerAPI: Served Swagger specification file (OpenAPI).
SwaggerUI: Project's Swagger itself as a user interface.