Generate OpenAPI specifications

The Squid Backend SDK provides decorators to automatically generate an OpenAPI specification, and expose your APIs for your backend project.

With Squid, you can create a feature-rich API

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. It provides the information developers need to understand and interact with the remote service without implementation logic.

The Squid Backend SDK uses tsoa decorators to generate OpenAPI specifications. Tsoa is a framework with integrated OpenAPI compiler to build Node.js serve-side applications using TypeScript. For more information on available decorators see the tsoa documentation.

To create an OpenAPI endpoint, add the @Route decorator to a service that extends the SquidService base class in your backend project, and add the appropriate decorators to the OpenAPI endpoint function:

Backend code

import { SquidService } from '@squidcloud/backend';
import { Get, Query, Route } from 'tsoa';

@Route('example')
export class ExampleService extends SquidService {
  @Get('echo')
  echo(@Query() message: string): Promise<string> {
    return this.createOpenApiResponse(message, 200);
  }
}

Local development

When developing locally, the above endpoint has the following format:

https://[YOUR_APP_ID]-dev-[YOUR_SQUID_DEVELOPER_ID].[APP_REGION].squid.cloud/openapi/example/echo

Where example is the value from the @Route decorator and echo is the name of the function.

View the local OpenAPI spec at the URL with the following format:

https://[YOUR_APP_ID]-dev-[YOUR_SQUID_DEVELOPER_ID].[APP_REGION].squid.cloud/openapi/spec.json

Deploying to dev

When deployed to dev, the above endpoint has the following format:

https://[YOUR_APP_ID]-dev.[APP_REGION].squid.cloud/openapi/example/echo

Where example is the value from the @Route decorator and echo is the name of the function.

View the deployed dev OpenAPI spec at the URL with the following format:

https://[YOUR_APP_ID]-dev.[APP_REGION].squid.cloud/openapi/spec.json

Deploying to prod

When deployed to prod, the endpoint has the following format:

https://[YOUR_APP_ID].[APP_REGION].squid.cloud/openapi/example/echo

Where example is the value from the @Route decorator and echo is the name of the function.

View the deployed prod OpenAPI spec at the URL with the following format:

https://[YOUR_APP_ID].[APP_REGION].squid.cloud/openapi/spec.json

Monitoring your endpoint

To view your Open API controllers, specs, and usage, navigate to the Backend tab of the Squid Cloud Console and click OpenAPI.

Customizing API Specification with tsoa.json

To further customize and enhance your OpenAPI specifications, you can include a tsoa.json configuration file in your project. This file allows you to define advanced settings such as security definitions, controllers paths, and the specification output directory.

Creating the tsoa.json File

Create a tsoa.json file in the root of your project with the following content to configure your API specifications:

{
  "entryFile": "src/service/index.ts",
  "noImplicitAdditionalProperties": "throw-on-extras",
  "controllerPathGlobs": [
    "src/**/*.ts"
  ],
  "spec": {
    "outputDirectory": "dist",
    "specVersion": 3,
    "securityDefinitions": {
      "apiKeyAuth": {
        "type": "apiKey",
        "name": "my-api-key-header",
        "in": "header"
      }
    }
  },
  "routes": {
    "routesDir": "dist",
    "middlewareTemplate": "./node_modules/@squidcloud/local-backend/dist/local-backend/openapi-template.hbs"
  }
}

This configuration sets up your project to output OpenAPI specification files to the dist directory and defines an API key authentication method named apiKeyAuth.

Adding Security to Endpoints

To enforce security on your API endpoints, you can use the @Security decorator from tsoa. This decorator can be added to individual methods or at the class level to apply to all methods within the class. Here's an example of how to secure an endpoint using the API key defined in tsoa.json:

Backend code

import { Get, Route, Security } from 'tsoa';

@Route('secure-example')
@Security('apiKeyAuth')
export class SecureExampleService {
  @Get('data')
  secureData(): Promise<string> {
    // Method implementation goes here
    return Promise.resolve('Secure data accessed');
  }
}

In the example above, the @Security decorator specifies that the apiKeyAuth security definition applies to all endpoints within the SecureExampleService. This means that clients must include the correct API key in the headers to access these endpoints.

Conclusion

By using a tsoa.json file, you can customize the generation of your OpenAPI specifications and add important features like authentication to your APIs. Remember, the @Security decorator only adds the security requirements to the OpenAPI spec; you must still implement the logic to verify the security credentials within your service methods.

Integrating these settings enhances the security and functionality of your API, making it robust and easier to use securely.