API Documentation
RapidREST builds a complete OpenAPI spec from your route classes automatically, no separate spec file to maintain, see Default Routes → OpenAPI for where that spec is actually exposed. What goes into it for a hand-written route, beyond the path and verb it already knows, comes from a small set of decorators.
@Summary('Delete a pet by ID')
@Description('Removes the pet permanently from the service.')
@Returns([null])
@Delete('/:id')
async deletePet(@Param('id') id: string) {
/* ... */
}
| Decorator | Adds |
|---|---|
@Summary(text) | A one-line summary for the endpoint |
@Description(text) | A longer description |
@Returns(types?) | The return type(s) shown in the spec, when TypeScript's own inferred return type isn't specific enough (a union, or a generic collection) |
@TypeInfo(types?) | The same idea as @Returns, but for a class property rather than a method |
@Example(value) | An example value for a property or return value |
@Default(value) | The default value of a property |
@Format(value) | A property's underlying format, e.g. 'date-time', 'int64' |
@Tags(values) | Searchable tags grouping related endpoints together |
All of these are thin wrappers around a single general-purpose @Document({...}) decorator, reach for the specific one that matches what you're describing, they compose the same way any other decorators do:
@Summary('List pets')
@Tags(['pets', 'catalog'])
@Returns([[Array, Pet]])
@Get()
async findPets(): Promise<Pet[]> {
/* ... */
}
@Returns([[Array, Pet]]) is how a generic collection type gets expressed, an array whose first element is the collection type and second is what it contains, since TypeScript's own reflection metadata can't describe generics at runtime on its own.
None of this is required. A route with no doc decorators at all still shows up in the generated spec, with its path, verb, and parameters, just without a summary or description alongside it. Add them where the extra context is worth having, an internal admin endpoint probably doesn't need one, a documented public API endpoint usually does.