Generate OpenAPI specifications

The Squid Backend SDK provides decorators to automatically generate an OpenAPI specification and expose custom APIs.

With Squid, you can create a feature-rich API.

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface for HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service. It provides the information developers need to understand and interact with a remote service without knowing the details of its implementation.

The Squid Backend SDK uses tsoa decorators to generate OpenAPI specifications. Tsoa is a framework with an integrated OpenAPI compiler to build Node.js server-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);
  }
}

Endpoint location

Locally

When developing locally, the above endpoint has the following format. example is the value from the @Route decorator and echo is the name of the function:

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

You can view the detailed OpenAPI spec locally at the URL with the following format:

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

Deployed

When deployed to dev, the above endpoint has the following format. example is the value from the @Route decorator and echo is the name of the function:

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

You can 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

When deployed to prod, the endpoint has the following format. example is the value from the @Route decorator and echo is the name of the function:

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

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 Console and click OpenAPI.

Customizing the API Specification

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 backend 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.