{"id":13781390,"url":"https://github.com/reg2005/adonis5-swagger","last_synced_at":"2025-12-30T00:55:19.427Z","repository":{"id":41970243,"uuid":"282039632","full_name":"reg2005/adonis5-swagger","owner":"reg2005","description":"Swagger provider for AdonisJS 5","archived":false,"fork":false,"pushed_at":"2022-04-21T13:25:32.000Z","size":2380,"stargazers_count":104,"open_issues_count":4,"forks_count":8,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-13T11:17:27.963Z","etag":null,"topics":["adonis5-swagger","hacktoberfest","swagger","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reg2005.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-23T19:36:43.000Z","updated_at":"2025-03-25T03:06:21.000Z","dependencies_parsed_at":"2022-08-12T01:00:40.033Z","dependency_job_id":null,"html_url":"https://github.com/reg2005/adonis5-swagger","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reg2005%2Fadonis5-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reg2005%2Fadonis5-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reg2005%2Fadonis5-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reg2005%2Fadonis5-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reg2005","download_url":"https://codeload.github.com/reg2005/adonis5-swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253580385,"owners_count":21930933,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adonis5-swagger","hacktoberfest","swagger","typescript"],"created_at":"2024-08-03T18:01:25.546Z","updated_at":"2025-12-30T00:55:19.390Z","avatar_url":"https://github.com/reg2005.png","language":"TypeScript","funding_links":[],"categories":["Packages"],"sub_categories":[],"readme":"\n# adonis5-swagger\n\u003e Swagger, AdonisJS, SwaggerUI\n\n[![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]\n\nCreate API documentation easily in Adonis 5 using [Swagger](https://swagger.io/specification/)\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n## Table of contents\n\n- [Installation](#installation)\n- [Sample Usage](#sample-usage)\n- [Best usage](#best-usage)\n- [Custom UI](#custom-ui)\n- [Build swagger spec file](#build-swagger-spec-file)\n- [Swagger modes](#swagger-modes)\n- [Production using](#production-using)\n- [Swagger basic auth](#swagger-basic-auth)\n- [Recipes](#recipes)\n  - [JWT auth for endpoints](#jwt-auth-for-endpoints)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n# Installation\n```bash\nnpm i --save adonis5-swagger\n```\nCompile your code:\n```bash\nnode ace serve --watch\n```\nConnect all dependences:\n```bash\nnode ace invoke adonis5-swagger\n```\n* For other configuration, please update the `config/swagger.ts`.\n\n# Sample Usage\n* Add new route:\n  ```js\n  Route.get('/api/hello', 'TestController.hello')\n  ```\n\n* Create `TestController` using `node ace make:controller Test` command:\n\n```js\n\timport { HttpContextContract } from \"@ioc:Adonis/Core/HttpContext\";\n\timport User from \"App/Models/User\";\n\n\texport default class UsersController {\n\t\t/**\n\t\t* @swagger\n\t\t* /api/users:\n\t\t* post:\n\t\t*     tags:\n\t\t*       - Users\n\t\t*     requestBody:\n\t\t*       required: true\n\t\t*       content:\n\t\t*         application/json:\n\t\t*           description: User payload\n\t\t*           schema:\n\t\t*             type: object\n\t\t*             properties:\n\t\t*               phone:\n\t\t*                 type: string\n\t\t*                 example: 'James Bond'\n\t\t*                 required: true\n\t\t*               email:\n\t\t*                 type: string\n\t\t*                 example: 'Bond007@example.com'\n\t\t*                 required: true\n\t\t*     produces:\n\t\t*       - application/json\n\t\t*     responses:\n\t\t*       200:\n\t\t*         description: Success\n\t\t*         content:\n\t\t*           application/json:\n\t\t*             schema:\n\t\t*               $ref: '#/components/schemas/User'\n\t\t*/\n\t\tpublic async create({ request, response }: HttpContextContract): Promise\u003cUser\u003e {\n\t\t\t\t// User saving and returns\n\t\t}\n\t}\n```\n\n* You can also define the schema in the Models:\n```js\n\t\timport {DateTime} from 'luxon'\n\t\timport {BaseModel, column} from '@ioc:Adonis/Lucid/Orm'\n\n\t\t/**\n\t\t* @swagger\n\t\t* components:\n\t\t\t* schemas:\n\t\t\t*      User:\n\t\t\t*        type: object\n\t\t\t*        properties:\n\t\t\t*          name:\n\t\t\t*            type: string\n\t\t\t*          email:\n\t\t\t*            type: string\n\t\t\t* \n\t\t*/\n\t\texport default class User extends BaseModel {\n\t\t@column({isPrimary: true})\n\t\tpublic id: number\n\t\t\n\t\t@column()\n\t\tpublic name: string\n\t\t\n\t\t@column()\n\t\tpublic email: string\n\t\t\n\t\t@column.dateTime({autoCreate: true})\n\t\tpublic createdAt: DateTime\n\t\t\n\t\t@column.dateTime({autoCreate: true, autoUpdate: true})\n\t\tpublic updatedAt: DateTime\n\t}\n  ```\n\n* Or create a separate file containing documentation from the APIs in either TS or YAML formats, sample structure:\n  ```bash\n  project\n  ├── app\n  ├── config \n  ├── docs\n  │   ├── controllers\n  │   │   ├── **/*.ts\n  │   │   ├── **/*.yml\n  │   └── models\n  │       ├── **/*.ts\n  │       ├── **/*.yml\n  ```\n# Best usage\n* Create files into docs/swagger, for example docs/swagger/auth.yml may contains:\n\n```YAML\n/api/auth/login:\n  post:\n    tags:\n      - Auth\n    security: []\n    description: Login\n    parameters:\n      - name: credentials\n        in:  body\n        required: true\n        schema:\n          properties:\n            phone:\n              type: string\n              example: '1234567890'\n              required: true\n    produces:\n      - application/json\n    responses:\n      200:\n        description: Success\n```\n* You can change default settings in config/swagger.ts\n* For other sample in YAML and JS format, please refer to this [link](/sample).\n\nOpen http://localhost:3333/docs in your browser\nFor detail usage, please check the Swagger specification in this [SwaggerSpec](https://swagger.io/specification/)\n\n# Custom UI\nFor using custom ui you should use own build of swagger ui. Current package contains only preconfigured and already built ui bundle. For example, you can use [Adonis Edge](https://preview.adonisjs.com/packages/edge) for rendering ui with custom params.\n\nFirst, install edge:\n```bash\nnpm i @adonisjs/view\n```\nOnce installed, run the following ace command to setup the package.\n```bash\nnode ace invoke @adonisjs/view\n```\nGenerate new template file using Adonis generator:\n```bash\nnode ace make:view swagger\n```\n\nAnd then add route for custom UI:\n```js\nRoute.get('/', async ({ view }) =\u003e {\n\tconst specUrl = 'your spec url'\n\treturn view.render('swagger', { specUrl })\n})\n```\n\nYour template should have similar content:\n```html\n\u003c!DOCTYPE html\u003e\n\u003chead\u003e\n\t\u003cscript src=\"//unpkg.com/swagger-ui-dist@3/swagger-ui-standalone-preset.js\"\u003e\u003c/script\u003e\n\t\u003cscript src=\"//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js\"\u003e\u003c/script\u003e\n\t\u003clink rel=\"stylesheet\" href=\"//unpkg.com/swagger-ui-dist@3/swagger-ui.css\"/\u003e\n\t\u003cscript\u003e\n\t\twindow.onload = () =\u003e {\n\t\t\tlet ui = SwaggerUIBundle({\n\t\t\t\turl: \"{{ specUrl }}\",\n\t\t\t\tdom_id: \"#swagger-ui\",\n\t\t\t\tpresets: [\n\t\t\t\t\tSwaggerUIBundle.presets.apis,\n\t\t\t\t\tSwaggerUIBundle.SwaggerUIStandalonePreset\n\t\t\t\t],\n\t\t\t\tplugins: [\n\t\t\t\t\tSwaggerUIBundle.plugins.DownloadUrl\n\t\t\t\t],\n\t\t\t})\n\n\t\t\twindow.ui = ui\n\t\t}\n\t\u003c/script\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\t\u003cdiv id=\"swagger-ui\"\u003e\u003c/div\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\nIt is the simplest way for using custom swagger ui, but of course you could use Webpack or another bundler tool for bundling your pre configured Swagger ui.\n# Build swagger spec file\n\nYou can build swagger spec file the next way:\n\nSet `specFilePath` option to your swagger config:\n```js\nconst swaggerConfig = {\n\tspecFilePath: 'docs/swagger.json'\n}\n```\nAnd then run adonis command:\n```bash\nnode ace swagger:generate\n```\nGenerated file will be written to by path configured in config.\n\n# Swagger modes\nThis package support two modes:\n- PRODUCTION\n- RUNTIME\n\nBy default RUNTIME mode enabled. When RUNTIME mode enabled package rebuild swagger spec file on each request. When you use PRODUCTION you should build your swagger spec once and then package will be respond this file content on each request.\n\n# Production using\nFor using swagger in production you should make some preparations:\n-\tSetup swagger config:\n```js\nconst swaggerConfig = { \n\tmode: process.env.NODE_ENV === 'production' ? 'PRODUCTION' : 'RUNTIME',\n\tspecFilePath: 'docs/swagger.json'\n}\n```\n- Add post hook for npm build script to your `package.json`:\n```json\n{\n\t\"scripts\": {\n\t\t\"build\": \"npm run compile\",\n\t\t\"postbuild\": \"node ace swagger:generate \u0026\u0026 cp -a docs/ build/docs\"\n\t}\n}\n```\n- Deliver your source code to production server.\n\n\n# Swagger basic auth\n\nPackage supports auth via basic auth schema. For using auth you should add config in `config/swagger.ts` \n\n```ts\nimport Env from '@ioc:Adonis/Core/Env'\n\nexport default {\n\t// ...Swagger congig\n\tswaggerAuth: {\n\t\tauthMiddleware: 'swagger-auth',\n\n\t\tauthCredentials: {\n\t\t\tlogin: Env.get('SWAGGER_AUTH_LOGIN'),\n\t\t\tpassword: Env.get('SWAGGER_AUTH_PASSWORD')\n\t\t}\n\t}\n}\n```\nRegister auth middleware in your `start/kernel.ts`\n```ts\nServer.middleware.registerNamed({\n  'swagger-auth': 'Adonis/Addons/Swagger/AuthMiddleware',\n})\n```\n\nThat's all. Your swagger docs secured by basic auth.\n\nInstead of using credentials, you can use function for verifying access in more complex way.\n```ts\nimport Env from '@ioc:Adonis/Core/Env'\nimport { verifyDocsAccess } from 'App/Services/Auth/Docs'\n\nexport default {\n\t// ...Swagger congig\n\tswaggerAuth: {\n\t\tauthMiddleware: 'swagger-auth',\n\n\t\tauthCheck: async (login, password) =\u003e {\n\t\t\treturn await verifyDocsAccess({ login, password })\n\t\t}\n\t}\n}\n```\n\n# Recipes\n\n## JWT auth for endpoints\n\nDefine JWT component inside your `.yaml` declaration:\n```\ncomponents:\n\tsecuritySchemes:\n\t\tbearerAuth:            \n\t\ttype: http\n\t\tscheme: bearer\n\t\tbearerFormat: JWT \n```\nOr add to your swagger config:\n```ts\nexport default {\n\t// ... config options\n\toptions: {\n\t\tdefinition: {\n\t\topenapi: '3.0.0',\n\t\tinfo: {\n\t\t\ttitle: 'Application with swagger docs',\n\t\t\tversion: '1.0.0',\n\t\t\tdescription: 'My application with swagger docs'\n\t\t},\n\t\tcomponents: {\n\t\t\tsecuritySchemes: {\n\t\t\tbearerAuth: {\n\t\t\t\ttype: \"http\",\n\t\t\t\tscheme: \"bearer\",\n\t\t\t\tbearerFormat: \"JWT\"\n\t\t\t}\n\t\t\t}\n\t\t}\n\t\t}\n\t//... config options\n\t}\n} as SwaggerConfig\n```\nThen you can add to your controller auth security option:\n```\n@swagger\n/api/users:\npost:\n\tsecurity:\n\t- bearerAuth: []\n```\n\n[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge\u0026logo=typescript\n[typescript-url]:  \"typescript\"\n\n[npm-image]: https://img.shields.io/npm/v/adonis5-swagger.svg?style=for-the-badge\u0026logo=npm\n[npm-url]: https://npmjs.org/package/adonis5-swagger \"npm\"\n\n[license-image]: https://img.shields.io/npm/l/adonis5-swagger?color=blueviolet\u0026style=for-the-badge\n[license-url]: LICENSE.md \"license\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freg2005%2Fadonis5-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freg2005%2Fadonis5-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freg2005%2Fadonis5-swagger/lists"}