pnpm i adonis-autoswagger #using pnpm- Creates paths automatically based on
routes.ts - Creates schemas automatically based on
app/Models/* - Creates schemas automatically based on
app/Interfaces/* - Rich configuration via comments
- Works also in production mode
node ace docs:generatecommand
Create a file /config/swagger.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,
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
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", swagger); to use Scalar instead
// return AutoSwagger.default.rapidoc("/swagger", swagger); to use RapiDoc instead
});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);
});Visit http://localhost:3333/docs to see AutoSwagger in action.
async docs(routes, conf): get the specification in YAML formatasync json(routes, conf): get the specification in JSON formatui(path, conf): get default swagger UIrapidoc(path, style): get rapidoc UIscalar(path): get scalar UIjsonToYaml(json): can be used to convertjson()back to yaml
For controllers to get detected properly, please load them lazily.
✅ const TestController = () => import('#controllers/test_controller')
❌ import TestController from '#controllers/test_controller'info See Swagger API General Info for details.
securitySchemes
Add/Overwrite security schemes Swagger Authentication for details.
// 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.
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);
});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.
//...
"imports": {
// ...
"#interfaces/*": "./app/custom/path/interfaces/*.js"
// ...
}
//...
Tags endpoints automatically
- If your routes are
/api/v1/products/...then your tagIndex should be3 - If your routes are
/v1/products/...then your tagIndex should be2 - If your routes are
/products/...then your tagIndex should be1
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.
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.
@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: <status> - <return> - <description>
<return> can be either a <Schema>, <Schema[]>/ or a custom JSON {}
@responseHeader (multiple)
Format: <status> - <name> - <description> - <meta>
@paramType (multiple)
Type can be one of Parameter Types (first letter in uppercase)
@requestBody (only one) A definition of the expected requestBody
Format: <body>
<body> can be either a <Schema>, <Schema[]>/, or a custom JSON {}
@requestFormDataBody (only one) A definition of the expected requestBody that will be sent with formData format.
Model
Format: <Model>
Custom format
Format: {"fieldname": {"type":"string", "format": "email"}}
This format should be a valid openapi 3.x json.
@responseBody <status> - Lorem ipsum Dolor sit amet
@responseBody <status> // returns standard <status> message
@responseBody <status> - <Model> // returns model specification
@responseBody <status> - <Model[]> // returns model-array specification
@responseBody <status> - <Model>.with(relations, property1, property2.relations, property3.subproperty.relations) // returns a model and a defined relation
@responseBody <status> - <Model[]>.with(relations).exclude(property1, property2, property3.subproperty) // returns model specification
@responseBody <status> - <Model[]>.append("some":"valid json") // append additional properties to a Model
@responseBody <status> - <Model[]>.paginated() // helper function to return adonisJS conform structure like {"data": [], "meta": {}}
@responseBody <status> - <Model>.only(property1, property2) // pick only specific properties
@responseBody <status> - {"foo": "bar", "baz": "<Model>"} //returns custom json object and also parses the model
@responseBody <status> - ["foo", "bar"] //returns custom json array// basicaly same as @response, just without a status
@paramPath <paramName> - Description - (meta)
@paramQuery <paramName> - 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)// basicaly same as @response, just without a status
@requestBody <Model> // Expects model specification
@requestBody <Model>.with(relations) // Expects model and its relations
@requestBody <Model[]>.append("some":"valid json") // append additional properties to a Model
@requestBody {"foo": "bar"} // Expects a specific JSON// Providing a raw JSON
@requestFormDataBody {"name":{"type":"string"},"picture":{"type":"string","format":"binary"}} // Expects a valid OpenAPI 3.x JSON// Providing a Model, and adding additional fields
@requestFormDataBody <Model> // Expects a valid OpenAPI 3.x JSON
@requestFormDataBody <Model>.exclude(property1).append("picture":{"type":"string","format":"binary"}) // Expects a valid OpenAPI 3.x JSONconfig/swagger.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
export default class SomeController {
/**
* @index
* @operationId getProducts
* @description Returns array of producs and it's relations
* @responseBody 200 - <Product[]>.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 - <Product>.with(user, user.relations)
* @responseBody 404
*/
public async show({ request, response }: HttpContextContract) {}
/**
* @update
* @responseBody 200
* @responseBody 404 - Product could not be found
* @requestBody <Product>
*/
public async update({ request, response }: HttpContextContract) {}
/**
* @custom
* @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 custom({ request, response }: HttpContextContract) {}
}AutoSwagger tries to extracat as much information as possible to generate swagger-docs for you.
Automatically generates swagger path-descriptions, based on your application routes. It also detects endpoints, protected by the auth-middlware.
Generates responses and requestBody based on your simple Controller-Annotation (see Examples)
Automatically generates swagger schema-descriptions based on your models
Instead of using param: any you can now use custom interfaces param: UserDetails. The interfaces files need to be located at app/Interfaces/
Add additional documentation to your Models properties.
Either use compose(BaseModel, SoftDeletes) or add a line @swagger-softdeletes to your Model.
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
// SomeModel.js
@hasMany(() => ProductView)
// @no-swagger
public views: HasMany<typeof ProductView>
@column()
// @enum(pending, active, deleted)
public status: string
@column()
// @example(johndoe@example.com)
public email: string
@column()
// @props({"minLength": 10})
public age: numberWarning
Make sure NODE_ENV=production in your production environment
To make it work in production environments, additional steps are required
-
Create a new command for
docs:generateSee official documentation- This should create a new file in
commands/DocsGenerate.ts
- This should create a new file in
-
Use the provided
DocsGenerate.ts.examle/DocsGeneratev6.ts.exampleand put its contents into your newly createdDocsGenerate.ts -
Execute the following
node ace docs:generate
node ace build --production
cp swagger.yml build/