API Reference

Swagger-Docs API Reference

This library has rich set of decorators and configuration options, which allows you to take your web apps API documentation to next level. API reference is divided in mainly following categories:

• Swagger configuration and setup
• Router configuration
• Route handler configuration
• DTO metadata

Swagger configuration and setup

These APIs allows you to configure and properly setup swagger with your web app.

1. SwaggerConfig

   Configure swagger OpenAPI specification. Following OpenAPI configuration can be made:

   1. .setTitle(string)
   2. .setDescription(string)
   3. .termsOfService(tosURLString)
   4. .setVersion(versionString)
   5. .addContactInfo({ name: string, url: string, email: string })
   6. .addLicenseInfo({ name: string, url: string })
   7. .addSecurity(securitySchemeName, securitySchemeObject)
   8. .addSecurityRequirement(securitySchemeName, requirement[])
   9. .addExternalDocumentation(externalDocsObject)

2. SwaggerDocs

   Add controllers and configure swagger UI to web framework app

   1. .bootstrapControllersToApp(controller[])
   2. .setup(webapp, pathWhereSwaggerUIServes)

Router configuration

These APIs allows you to configure router, which can be later bootstrapped with swagger docs as well as web app.

1. Controller
   • Decorator to mark class as controller which is superset of all the routes inside it
2. RouteMiddleware
   • Middleware decorator to add middleware function to route handler. This decorator can be applied to individual route handler inside controller and controller itself

Route handler configuration

These APIs allows you to define routes for your web app. These are further categorised into following sub-categories

• Arguments
• Methods
• Swagger metadata

Arguments

These APIs allows you to add route handler arguments and parameters.

1. PathParam
   • Decorator to indicate a path parameter inside route handler.
2. QueryParam
   • Decorator to indicate a query parameter inside route handler.
3. Header
   • Decorator to indicate a header inside route handler.
4. Body
   • Decorator to indicate a request body argument inside route handler.
5. Request
   • Decorator to indicate a request object argument inside route handler.
6. Response
   • Decorator to indicate a response object argument inside route handler.
7. Next
   • Decorator to indicate a next function argument inside route handler.
8. File
   • Decorator to indicate a file argument inside route handler. This will allow user to upload file from swagger also.

Methods

These APIs allows you to define http methods for your route handler.

1. Get
   • Decorator to indicate GET method for route handler.
2. Put
   • Decorator to indicate a PUT method for route handler.
3. Post
   • Decorator to indicate a POST method for route handler.
4. Delete
   • Decorator to indicate a DELETE method for route handler.
5. Options
   • Decorator to indicate a OPTIONS method for route handler
6. Head
   • Decorator to indicate a HEAD method for route handler
7. Patch
   • Decorator to indicate a PATCH method for route handler
8. Trace
   • Decorator to indicate a TRACE method for route handler

Swagger metadata

These APIs allows you to configure and properly setup swagger with your web app.

1. RouteResponseBody
   • Explicitly set response body for route handler
2. RouteRequestBody
   • Explicitly set request body for route handler
3. RouteTag
   • Attach swagger tag with route handler. This decorator can be applied to controller as well
4. RouteSummary
   • Add route handler summary shown in swagger UI. This decorator can be applied to controller as well.
5. RouteDescription
   • Add route handler description shown in swagger UI. This decorator can be applied to controller as well.
6. RouteExternalDocs
   • Add external docs links to route handler shown swagger UI. This decorator can be applied to controller as well.
7. RouteDeprecated
   • Set route handler as deprecated and no longer in use. This decorator can be applied to controller as well.
8. RouteSecurity
   • Set security for route handler and mark it protected api in swagger UI. This decorator can be applied to controller as well.
9. RouteServers
   • Set different servers which accepts the route path. This helps in selecting which server should be used as base when calling API. This decorator can be applied to controller as well.

DTO metadata

These APIs allows you to configure and properly setup swagger with your web app.

1. IsArray
   • This decorator marks the property as array inside DTO class.
2. IsBoolean
   • This decorator marks the property as boolean inside DTO class.
3. IsNumber
   • This decorator marks the property as number inside DTO class.
4. IsObject
   • This decorator marks the property as object inside DTO class.
5. IsString
   • This decorator marks the property as string inside DTO class.
6. IsEnum
   • This decorator marks the property as enum inside DTO class.