OpenAPI

Our SaaS boilerplate comes with built-in API documentation powered by OpenAPI (formerly known as Swagger). This feature provides a comprehensive and interactive documentation of your backend API, making it easier for developers to understand and interact with the available endpoints.

Accessing the API Documentation

Once your backend server is running, you can access the OpenAPI documentation by following these steps:

1. Ensure your backend server is running (typically on port 4001).

2. Open a web browser and navigate to:

   Copyhttp://localhost:4001/api

3. You will be presented with the OpenAPI UI, showing all available endpoints, request/response schemas, and other API details.

Features of the OpenAPI Documentation

1. Interactive Interface: The OpenAPI UI allows you to not only read about the API endpoints but also try them out directly from the browser.

2. Detailed Endpoint Information: For each endpoint, you can see:

   • The HTTP method (GET, POST, PUT, DELETE, etc.)

   • The route

   • Required parameters

   • Request body schema (for POST and PUT requests)

   • Response schemas

   • Authentication requirements

3. Model Schemas: View detailed schemas for all data models used in your API.

4. Try It Out: You can make actual API calls directly from the documentation interface to test endpoints.

Benefits of OpenAPI Documentation

• Easy Onboarding: New developers can quickly understand the API structure and capabilities.

• Testing: Easily test API endpoints without needing to set up a separate API client.

• Client Generation: The OpenAPI specification can be used to generate client libraries in various programming languages.

• Always Up-to-Date: As the documentation is generated from your code, it always reflects the current state of your API.

Extending the Documentation

As you add new endpoints or modify existing ones, the OpenAPI documentation will automatically update to reflect these changes. However, to make the most of this feature:

1. Use appropriate NestJS decorators and TypeScript types in your controllers and DTOs.

2. Add meaningful descriptions to your endpoints and DTO properties using OpenAPI decorators.

Example of enhanced documentation in a controller:

typescriptCopyimport { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';

@ApiTags('products')
@Controller('products')
export class ProductsController {
  @Get()
  @ApiOperation({ summary: 'Get all products' })
  @ApiResponse({ status: 200, description: 'Return all products.' })
  async findAll() {
    // ...
  }
}

By leveraging the OpenAPI documentation, you can ensure that your API is well-documented and easily accessible to all developers working on your SaaS project.

Remember to keep your API documentation secure if it contains sensitive information about your backend structure.