OpenAPI & Swagger UI
You are reading the documentation for version 2 of FoalTS. Instructions for upgrading to this version are available here. The old documentation can be found here.
#
IntroductionOpenAPI Specification (formerly known as Swagger Specification) is an API description format for REST APIs. An OpenAPI document allows developers to describe entirely an API.
Swagger UI is a graphical interface to visualize and interact with the API’s resources. It is automatically generated from one or several OpenAPI documents.
Example of OpenAPI document and Swagger Visualisation
#
Quick StartThis example shows how to generate a documentation page of your API directly from your hooks and controllers.
app.controller.ts
api.controller.ts
openapi.controller.ts
Result
#
OpenAPI#
The BasicsThe first thing to do is to add the @ApiInfo
decorator to the root controller of the API. Two attributes are required: the title
and the version
of the API.
Then each controller method can be documented with the @ApiOperation
decorator.
Beside the @ApiOperation
decorator, you can also use other decorators more specific to improve the readability of the code.
Operation Decorators |
---|
@ApiOperationSummary |
@ApiOperationId |
@ApiOperationDescription |
@ApiServer |
@ApiRequestBody |
@ApiSecurityRequirement |
@ApiDefineTag |
@ApiExternalDoc |
@ApiUseTag |
@ApiParameter |
@ApiResponse |
@ApiCallback |
Example
#
Don't Repeat Yourself and Decorate Sub-ControllersLarge applications can have many subcontrollers. FoalTS automatically resolves the paths for you and allows you to share common specifications between several operations.
Example
The generated document will then look like this:
#
Use Existing HooksThe addition of these decorators can be quite redundant with existing hooks. For example, if we want to write OpenAPI documentation for authentication and validation of the request body, we may end up with something like this.
To avoid this, the framework hooks already expose an API specification which is directly included in the generated OpenAPI document.
You can disable this behavior globally with the configuration key setting.openapi.useHooks
.
- YAML
- JSON
- JS
You can also disable it on a specific hook with the openapi
option.
#
Generate the API DocumentOnce the controllers are decorated, there are several ways to generate the OpenAPI document.
#
from the controllersDocuments can be retrieved with the OpenApi
service:
#
from a shell scriptThe createOpenApiDocument
function can also be used in a shell script to generate the document.
Note that this function instantiates the controllers. So if you have logic in your constructors, you may prefer to put it in
init
methods.
src/scripts/generate-openapi-doc.ts
#
using the Swagger UI controllerAnother alternative is to use the SwaggerController directly. This allows you to serve the document(s) at /openapi.json
and to use it (them) in a Swagger interface.
#
Swagger UI#
Simple caseapp.controller.ts
open-api.controller.ts
Opening the browser at the path /swagger
will display the documentation of the ApiController
.
#
With an URLIf needed, you can also specify the URL of a custom OpenAPI file (YAML or JSON).
#
Several APIs or VersionsSome applications may serve several APIs (for example two versions of a same API). Here is an example on how to handle this.
app.controller.ts
open-api.controller.ts
#
Using a Static FileIf you prefer to write manually your OpenAPI document, you can add an openapi.yml
file in the public/
directory and configure your SwaggerController
as follows:
#
Advanced#
Using Controller Properties#
In-Depth Overview- FoalTS automatically resolves the path items and operations based on your controller paths.
Example
- The decorators
@ApiServer
,@ApiSecurityRequirement
and@ApiExternalDocs
have a different behavior depending on if they decorate the root controller or a subcontroller / a method.
Example with the root controller
Example with a subcontroller / a method
#
Define and Reuse ComponentsOpenAPI allows you to define and reuse components. Here is a way to achieve this with Foal.
Component Decorators |
---|
@ApiDefineSchema |
@ApiDefineResponse |
@ApiDefineParameter |
@ApiDefineExample |
@ApiDefineRequestBody |
@ApiDefineHeader |
@ApiDefineSecurityScheme |
@ApiDefineLink |
@ApiDefineCallback |
The
@ApiDefineXXX
decorators can be added to any controllers or methods but they always define components in the global scope of the API the controller belongs to.
--
The schemas defined with these decorators can also be re-used in the
@ValidateXXX
hooks.
#
Generate and Save a Specification File with a Shell Scriptsrc/scripts/generate-openapi-doc.ts
#
Common ErrorsThis example will throw this error.
OpenAPI does not support paths that are identical with different parameter names. Here is a way to solve this issue:
#
Extend Swagger UI optionsSwagger UI options can be extended using the uiOptions
property.
Example