JSDoc
While creating routes is straightforward, it is crucial to provide essential information about your routes.
This is achieved by adding JSDoc comments to your route functions.
Operation ID and Tags
The operation ID serves as a unique identifier for each route. Swagger uses it to distinguish routes and as the route name in the generated documentation. Kita also relies on operation IDs to generate meaningful route names and related information.
Tags group routes together in the generated documentation.
/**
* Creates a new user
*
* @operationId createUser
* @tag Users
*/
export function post() {
return true;
}2
3
4
5
6
7
{
"paths": {
"/": {
"post": {
"operationId": "createUser",
"tags": ["Users"],
"description": "Creates a new user",
"responses": {
"2XX": {
"description": "Default Response",
"content": {
"application/json": { "schema": { "type": "boolean" } }
}
}
}
}
}
}
}2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Although it may seem like trivial information, it is crucial to ensure all generated code is meaningful and easily understandable.
Additionally, providing this data is necessary to adhere to the OpenAPI Specification.
Additional tags
@security
This tag specifies the security requirements for a route, mainly used to document authentication requirements.
/** @security bearerAuth */
export function post() {
return true;
}2
{
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearerAuth",
"bearerFormat": "JWT"
}
}
},
"paths": {
"/": {
"post": {
"operationId": "postIndex",
"security": [{ "bearerAuth": [] }],
"responses": {
"2XX": {
"description": "Default Response",
"content": {
"application/json": { "schema": { "type": "boolean" } }
}
}
}
}
}
}
}2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
It’s also required that all @security schemas are defined in the OpenAPI config:
import { Kita } from '@kitajs/runtime';
import fastify from 'fastify';
const app = fastify();
app.register(Kita, {
fastifySwagger: {
openapi: {
components: {
securitySchemes: {
// Register the bearerAuth security scheme used above
bearerAuth: {
type: 'http',
scheme: 'bearerAuth',
bearerFormat: 'JWT'
}
}
}
}
}
});2
3
4
TIP
Prefer using authentication through a Kita Provider and use this tag only to document it.
@throws
This tag specifies errors that Kita cannot detect automatically. When throwing manually created errors, use the HttpErrors parameter.
:::
/**
* @throws 401
* @throws 402
*
* Or multiple errors at once
* @throws 401, 402
*/
export function get() {
return true;
}2
3
4
5
6
7
8
{
"components": {
"schemas": {
"HttpError": {
"type": "object",
"properties": {
"statusCode": { "type": "number" },
"code": { "type": "string" },
"error": { "type": "string" },
"message": { "type": "string" }
}
}
}
},
"paths": {
"/": {
"get": {
"operationId": "getIndex",
"responses": {
"401": {
"description": "Default Response",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/HttpError" }
}
}
},
"402": {
"description": "Default Response",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/HttpError" }
}
}
},
"2XX": {
"description": "Default Response",
"content": {
"application/json": { "schema": { "type": "boolean" } }
}
}
}
}
}
}
}2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
:::
@summary
A brief summary of the route.
/** @summary Creates a new user */
export function get() {
return true;
}2
{
"paths": {
"/": {
"get": {
"operationId": "getIndex",
"summary": "Creates a new user",
"responses": {
"2XX": {
"description": "Default Response",
"content": {
"application/json": { "schema": { "type": "boolean" } }
}
}
}
}
}
}
}2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
@description
A more detailed description of the route.
It defaults to the text description, but @description can be used to provide a more detailed explanation and hide the text description.
/** Text description shown in the documentation */
export function get() {
return true;
}
/**
* Internal description of the code that is not shown in the documentation
*
* @description Text description shown in the documentation
*/
export function post() {
return true;
}2
{
"paths": {
"/": {
"get": {
"operationId": "getIndex",
"description": "Text description shown in the documentation",
"responses": {
"2XX": {
"description": "Default Response",
"content": {
"application/json": { "schema": { "type": "boolean" } }
}
}
}
},
"post": {
"operationId": "postIndex",
"description": "Text description shown in the documentation",
"responses": {
"2XX": {
"description": "Default Response",
"content": {
"application/json": { "schema": { "type": "boolean" } }
}
}
}
}
}
}
}2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
@url
Used to change the URL of the route, especially when deviating from a filesystem path structure.
WARNING
Using this tag is not recommended. Always follow the filesystem path for consistency.
/** @url /users */
export function get() {
return true;
}2
{
"paths": {
"/users": {
"get": {
"operationId": "getIndex",
"responses": {
"2XX": {
"description": "Default Response",
"content": {
"application/json": { "schema": { "type": "boolean" } }
}
}
}
}
}
}
}2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
@deprecated
Marks a route as deprecated, indicating this in the generated documentation.
/** @deprecated */
export function get() {
return true;
}2
{
"paths": {
"/": {
"get": {
"operationId": "getIndex",
"deprecated": true,
"responses": {
"2XX": {
"description": "Default Response",
"content": {
"application/json": { "schema": { "type": "boolean" } }
}
}
}
}
}
}
}2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
@internal
Marks a route as internal, hiding it from the generated documentation but still allowing application usage.
/** @internal */
export function get() {}2
{
// The route is not present in the generated documentation
"paths": {}
}2
3
4