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:
Ensure your backend server is running (typically on port 4001).
Open a web browser and navigate to:
You will be presented with the OpenAPI UI, showing all available endpoints, request/response schemas, and other API details.
Features of the OpenAPI Documentation
Interactive Interface: The OpenAPI UI allows you to not only read about the API endpoints but also try them out directly from the browser.
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
Model Schemas: View detailed schemas for all data models used in your API.
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:
Use appropriate NestJS decorators and TypeScript types in your controllers and DTOs.
Add meaningful descriptions to your endpoints and DTO properties using OpenAPI decorators.
Example of enhanced documentation in a controller:
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.
Last updated