Documentation

The system has a mechanism for automatically collecting documentation in the OpenAPI format. It is displayed as an HTML page using Swagger UI at /api-docs.

You can also download the specification file from the URL /api-docs/download and use it in external tools.

Most methods require authorization, so when using the documentation, first execute the User.login method and specify the obtained JWT in the authorization section (the Authorize button in the top right corner of the page).

Documentation is generated for class methods based on the generics of input and output parameters. Documenting comments are also included in the documentation. Types and interfaces, except for base types, go into the documentation schemas section.

To include a method in the documentation, it must be marked with the @OpenApi() decorator directly above the function (after the documenting comment).

If a parameter in a generic is anonymous, meaning the object description is in curly braces, then all custom types and interfaces used inside will be fully expanded in the final documentation, which can sometimes be inconvenient for reading. If you want the name of the type/interface to remain there, create it and use it in the generic.

Example with an anonymous type/interface:

@OpenApi()  
async create(r: IAPIRequest<{  
   orders: ICreatePmntOrder[]  
   for_user_id?: number  
}>)

Example with an external type/interface:

export interface ICreatePaymentRequest {  
   orders: ICreatePmntOrder[]  
   for_user_id?: number  
}

@OpenApi()  
async create(r: IAPIRequest<ICreatePaymentRequest>):

Documentation assembly is carried out with the command “node ./openAPI/openApi.js”; there is a corresponding script in package.json.

The final file is located in openAPI/swagger.yaml. It is recreated every time, so it should not be edited manually.

Please write sufficient documenting comments for functions. Also, write comments for parameters if their behavior is not obvious or not described above. If you are writing a module, it is recommended to describe the logic of operation and boundary conditions at the beginning of the file. If separate documentation is maintained for the project, keep it up to date in agreement with the project manager/team lead.