Adonis AutoSwagger

![Version]()
![GitHub stars]()
![GitHub watchers]()
![GitHub forks]()

$3

💻️ Install

``bash
pnpm i adonis-autoswagger #using pnpm
`

---

⭐️ Features

- Creates paths automatically based on routes.ts
- Creates schemas automatically based on app/Models/*
- Creates schemas automatically based on app/Interfaces/*
- Creates schemas automatically based on app/Validators/* (only for adonisJS v6)
- Creates schemas automatically based on app/Types/* (only for adonisJS v6)
- Rich configuration via comments
- Works also in production mode
- node ace docs:generate command

---

✌️Usage

Create a file /config/swagger.ts

`ts
// for AdonisJS v6
import path from "node:path";
import url from "node:url";
// ---

export default {
// path: __dirname + "/../", for AdonisJS v5
path: path.dirname(url.fileURLToPath(import.meta.url)) + "/../", // for AdonisJS v6
title: "Foo", // use info instead
version: "1.0.0", // use info instead
description: "", // use info instead
tagIndex: 2,
productionEnv: "production", // optional
info: {
title: "title",
version: "1.0.0",
description: "",
},
snakeCase: true,

debug: false, // set to true, to get some useful debug output
ignore: ["/swagger", "/docs"],
preferredPutPatch: "PUT", // if PUT/PATCH are provided for the same route, prefer PUT
common: {
parameters: {}, // OpenAPI conform parameters that are commonly used
headers: {}, // OpenAPI conform headers that are commonly used
},
securitySchemes: {}, // optional
authMiddlewares: ["auth", "auth:api"], // optional
defaultSecurityScheme: "BearerAuth", // optional
persistAuthorization: true, // persist authorization between reloads on the swagger page
showFullPath: false, // the path displayed after endpoint summary
};
`

In your routes.ts

6️⃣ for AdonisJS v6

`js
import AutoSwagger from "adonis-autoswagger";
import swagger from "#config/swagger";
// returns swagger in YAML
router.get("/swagger", async () => {
return AutoSwagger.default.docs(router.toJSON(), swagger);
});

// Renders Swagger-UI and passes YAML-output of /swagger
router.get("/docs", async () => {
return AutoSwagger.default.ui("/swagger", swagger);
// return AutoSwagger.default.scalar("/swagger"); to use Scalar instead. If you want, you can pass proxy url as second argument here.
// return AutoSwagger.default.rapidoc("/swagger", "view"); to use RapiDoc instead (pass "view" default, or "read" to change the render-style)
});
`

5️⃣ for AdonisJS v5

`js
import AutoSwagger from "adonis-autoswagger";
import swagger from "Config/swagger";
// returns swagger in YAML
Route.get("/swagger", async () => {
return AutoSwagger.docs(Route.toJSON(), swagger);
});

// Renders Swagger-UI and passes YAML-output of /swagger
Route.get("/docs", async () => {
return AutoSwagger.ui("/swagger", swagger);
});
`

$3

Visit http://localhost:3333/docs to see AutoSwagger in action.

$3

- async docs(routes, conf): get the specification in YAML format
- async json(routes, conf): get the specification in JSON format
- ui(path, conf): get default swagger UI
- rapidoc(path, style): get rapidoc UI
- scalar(path, proxyUrl): get scalar UI
- stoplight(path, theme): get stoplight elements UI
- jsonToYaml(json): can be used to convert json() back to yaml

---

💡 Compatibility

For controllers to get detected properly, please load them lazily.

`ts
✅ const TestController = () => import('#controllers/test_controller')
❌ import TestController from '#controllers/test_controller'
`

🧑‍💻 Advanced usage

$3

info
See Swagger API General Info for details.

securitySchemes

Add/Overwrite security schemes Swagger Authentication for details.

`ts
// example to override ApiKeyAuth
securitySchemes: {
ApiKeyAuth: {
type: "apiKey"
in: "header",
name: "X-API-Key"
}
}
`

defaultSecurityScheme

Override the default security scheme.

- BearerAuth
- BasicAuth
- ApiKeyAuth
- your own defined under securitySchemes

authMiddlewares

If a route uses a middleware named auth, auth:api, AutoSwagger will detect it as a Swagger security method. However, you can implement other middlewares that handle authentication.

$3

`ts
Route.get("/myswagger", async () => {
const json = await AutoSwagger.json(Route.toJSON(), swagger);
// modify json to your hearts content
return AutoSwagger.jsonToYaml(json);
});

Route.get("/docs", async () => {
return AutoSwagger.ui("/myswagger", swagger);
});
`

$3

AutoSwagger supports the paths set in package.json. Interfaces are expected to be in app/interfaces. However, you can override this, by modifying package.json as follows.

`json
//...
"imports": {
// ...
"#interfaces/": "./app/custom/path/interfaces/.js"
// ...
}
//...

`

---

📃 Configure

$3

Tags endpoints automatically

- If your routes are /api/v1/products/... then your tagIndex should be 3
- If your routes are /v1/products/... then your tagIndex should be 2
- If your routes are /products/... then your tagIndex should be 1

$3

Ignores specified paths. When used with a wildcard (\*), AutoSwagger will ignore everything matching before/after the wildcard.
/test/_will ignore everything starting with/test/, whereas \*/testwill ignore everything ending with/test.

$3

Sometimes you want to use specific parameters or headers on multiple responses.

_Example:_ Some resources use the same filter parameters or return the same headers.

Here's where you can set these and use them with @paramUse() and @responseHeader() @use(). See practical example for further details.

---

💫 Extend Controllers

Add additional documentation to your Controller-files

@summary (only one)
A summary of what the action does

@tag (only one)
Set a custom tag for this action

@description (only one)
A detailed description of what the action does.

@operationId (only one)
An optional unique string used to identify an operation. If provided, these IDs must be unique among all operations described in your API..

@responseBody (multiple)

Format: - -

can be either a , / or a custom JSON {}

@responseHeader (multiple)

Format: - - -

@paramType (multiple)

Type can be one of Parameter Types (first letter in uppercase)

@requestBody (only one)
A definition of the expected requestBody

Format:

can be either a , /, or a custom JSON {}

@requestFormDataBody (only one)
A definition of the expected requestBody that will be sent with formData format.

Schema
A model or a validator.
Format:

Custom format

Format: {"fieldname": {"type":"string", "format": "email"}}
This format should be a valid openapi 3.x json.

---

🤘Examples

@responseBody examples

`ts
@responseBody - Lorem ipsum Dolor sit amet

@responseBody // returns standard message

@responseBody - // returns model specification

@responseBody - // returns model-array specification

@responseBody - .with(relations, property1, property2.relations, property3.subproperty.relations) // returns a model and a defined relation

@responseBody - .with(relations).exclude(property1, property2, property3.subproperty) // returns model specification

@responseBody - .append("some":"valid json") // append additional properties to a Model

@responseBody - .paginated() // helper function to return adonisJS conform structure like {"data": [], "meta": {}}

@responseBody - .paginated(dataName, metaName) // returns a paginated model with custom keys for the data array and meta object, use .paginated(dataName) or .paginated(,metaName) if you want to override only one. Don't forget the ',' for the second parameter.

@responseBody - .only(property1, property2) // pick only specific properties

@requestBody // returns a validator object

@responseBody - {"foo": "bar", "baz": ""} //returns custom json object and also parses the model
@responseBody - ["foo", "bar"] //returns custom json array
`

@paramPath and @paramQuery examples

`ts
// basicaly same as @response, just without a status
@paramPath - Description - (meta)
@paramQuery - Description - (meta)

@paramPath id - The ID of the source - @type(number) @required
@paramPath slug - The ID of the source - @type(string)

@paramQuery q - Search term - @type(string) @required
@paramQuery page - the Page number - @type(number)

`

@requestBody examples

`ts
// basicaly same as @response, just without a status
@requestBody // Expects model specification
@requestBody // Expects validator specification
@requestBody .with(relations) // Expects model and its relations
@requestBody .append("some":"valid json") // append additional properties to a Model
@requestBody {"foo": "bar"} // Expects a specific JSON
`

@requestFormDataBody examples

`ts
// Providing a raw JSON
@requestFormDataBody {"name":{"type":"string"},"picture":{"type":"string","format":"binary"}} // Expects a valid OpenAPI 3.x JSON
`

`ts
// Providing a Model, and adding additional fields
@requestFormDataBody // Expects a valid OpenAPI 3.x JSON
@requestFormDataBody .exclude(property1).append("picture":{"type":"string","format":"binary"}) // Expects a valid OpenAPI 3.x JSON
`

---

Practical example

config/swagger.ts

`ts
export default {
path: __dirname + "../",
title: "YourProject",
version: "1.0.0",
tagIndex: 2,
ignore: ["/swagger", "/docs", "/v1", "/", "/something/", "/something"],
common: {
parameters: {
sortable: [
{
in: "query",
name: "sortBy",
schema: { type: "string", example: "foo" },
},
{
in: "query",
name: "sortType",
schema: { type: "string", example: "ASC" },
},
],
},
headers: {
paginated: {
"X-Total-Pages": {
description: "Total amount of pages",
schema: { type: "integer", example: 5 },
},
"X-Total": {
description: "Total amount of results",
schema: { type: "integer", example: 100 },
},
"X-Per-Page": {
description: "Results per page",
schema: { type: "integer", example: 20 },
},
},
},
},
};
`

app/Controllers/Http/SomeController.ts

`ts
export default class SomeController {
/**
* @index
* @operationId getProducts
* @description Returns array of producs and it's relations
* @responseBody 200 - .with(relations)
* @paramUse(sortable, filterable)
* @responseHeader 200 - @use(paginated)
* @responseHeader 200 - X-pages - A description of the header - @example(test)
*/
public async index({ request, response }: HttpContextContract) {}

/**
* @show
* @paramPath id - Describe the path param - @type(string) @required
* @paramQuery foo - Describe the query param - @type(string) @required
* @description Returns a product with it's relation on user and user relations
* @responseBody 200 - .with(user, user.relations)
* @responseBody 404
*/
public async show({ request, response }: HttpContextContract) {}

/**
* @update
* @responseBody 200
* @responseBody 404 - Product could not be found
* @requestBody
*/
public async update({ request, response }: HttpContextContract) {}

/**
* @myCustomFunction
* @summary Lorem ipsum dolor sit amet
* @paramPath provider - The login provider to be used - @enum(google, facebook, apple)
* @responseBody 200 - {"token": "xxxxxxx"}
* @requestBody {"code": "xxxxxx"}
*/
public async myCustomFunction({ request, response }: HttpContextContract) {}
}
`

---

What does it do?

AutoSwagger tries to extracat as much information as possible to generate swagger-docs for you.

Paths

Automatically generates swagger path-descriptions, based on your application routes. It also detects endpoints, protected by the auth-middlware.

!paths

$3

Generates responses and requestBody based on your simple Controller-Annotation (see Examples)

---

Schemas

$3

Automatically generates swagger schema-descriptions based on your models

!alt

$3

Instead of using param: any you can now use custom interfaces param: UserDetails. The interfaces files need to be located at app/Interfaces/

$3

If you use enums in your models, AutoSwagger will detect them from app/Types/ folder and add them to the schema.
If you want to add enum on ExampleValue, you can use .append(enumFieldExample)

Example:

`ts
@responseBody 200 - .with(relations).append(enumFieldExample)
`

Extend Models

Add additional documentation to your Models properties.

$3

Either use compose(BaseModel, SoftDeletes) or add a line @swagger-softdeletes to your Model.

Attention

The below comments MUST be placed 1 line above the property.

---

@no-swagger
Although, autoswagger detects serializeAs: null fields automatically, and does not show them. You can use @no-swagger for other fields.

@enum(foo, bar)
If a field has defined values, you can add them into an enum. This is usesfull for something like a status field.

@format(string)
Specify a format for that field, i.e. uuid, email, binary, etc...

@example(foo bar)
Use this field to provide own example values for specific fields

@props({"minLength": 10, "foo": "bar"})
Use this field to provide additional properties to a field, like minLength, maxLength, etc. Needs to bee valid JSON.

@required
Specify that the field is required

`ts
// SomeModel.js
@hasMany(() => ProductView)
// @no-swagger
public views: HasMany


@column()
// @enum(pending, active, deleted)
public status: string

@column()
// @example(johndoe@example.com)
public email: string

@column()
// @props({"minLength": 10})
public age: number

`

---

Production environment

> [!WARNING]
> Make sure NODE_ENV=production in your production environment or whatever you set in options.productionEnv

To make it work in production environments, additional steps are required

- Create a new command for docs:generate See official documentation

- This should create a new file in commands/DocsGenerate.ts

- Use the provided DocsGenerate.ts.examle/DocsGeneratev6.ts.example and put its contents into your newly created DocsGenerate.ts

- Modify /start/env.ts as follows

`ts
//...
// this is necessary to make sure that the DocsGenerate command will run in CI/CD pipelines without setting environment variables
const isNodeAce = process.argv.some(
(arg) => arg.endsWith("/ace") || arg === "ace"
);

export default await Env.create(
new URL("../", import.meta.url),
isNodeAce
? {}
: {
// leave other settings as is
NODE_ENV: Env.schema.enum([
"development",
"production",
"test",
] as const),
PORT: Env.schema.number(),
}
);

//...
`

- Execute the following

`bash
node ace docs:generate
node ace build --production
cp swagger.yml build/
`

Known Issues

- Interfaces with objects are not working like interface Test {foo: {bar: string}}`
- Solution, just extract the object as it's own interface