{"id":14986641,"url":"https://github.com/theoomoregbee/sails-hook-swagger-generator","last_synced_at":"2026-03-16T22:37:50.791Z","repository":{"id":38176022,"uuid":"99695966","full_name":"theoomoregbee/sails-hook-swagger-generator","owner":"theoomoregbee","description":"A tool to help generate Swagger specification documentation based on OAS 3.0 for Sails APIs","archived":false,"fork":false,"pushed_at":"2023-01-12T08:45:29.000Z","size":4688,"stargazers_count":80,"open_issues_count":13,"forks_count":33,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-02T16:07:12.872Z","etag":null,"topics":["api","documentation","jsdoc-comments","jsdoc-documentation","json","node","nodejs","openapi-definitions","openapi-generator","openapi-specification","openapi3","redoc","sailsjs","swagger","swagger-documentation-json","swagger-node","swagger-specification"],"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/theoomoregbee.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-08-08T13:27:48.000Z","updated_at":"2025-04-01T01:14:06.000Z","dependencies_parsed_at":"2023-02-09T11:01:18.763Z","dependency_job_id":null,"html_url":"https://github.com/theoomoregbee/sails-hook-swagger-generator","commit_stats":null,"previous_names":["theo4u/sails-hook-swagger-generator"],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theoomoregbee%2Fsails-hook-swagger-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theoomoregbee%2Fsails-hook-swagger-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theoomoregbee%2Fsails-hook-swagger-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theoomoregbee%2Fsails-hook-swagger-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theoomoregbee","download_url":"https://codeload.github.com/theoomoregbee/sails-hook-swagger-generator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248075387,"owners_count":21043577,"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":["api","documentation","jsdoc-comments","jsdoc-documentation","json","node","nodejs","openapi-definitions","openapi-generator","openapi-specification","openapi3","redoc","sailsjs","swagger","swagger-documentation-json","swagger-node","swagger-specification"],"created_at":"2024-09-24T14:13:16.322Z","updated_at":"2026-03-16T22:37:50.765Z","avatar_url":"https://github.com/theoomoregbee.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swagger Generator Sails Hook\n[![Travis](https://img.shields.io/travis/theoomoregbee/sails-hook-swagger-generator.svg)](https://travis-ci.org/theoomoregbee/sails-hook-swagger-generator)\n[![npm](https://img.shields.io/npm/v/sails-hook-swagger-generator.svg)](https://www.npmjs.com/package/sails-hook-swagger-generator)\n[![npm](https://img.shields.io/npm/l/sails-hook-swagger-generator.svg)]()\n[![npm](https://img.shields.io/npm/dt/sails-hook-swagger-generator.svg)](https://www.npmjs.com/package/sails-hook-swagger-generator)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n\n\nThis helps to create swagger documentation json which is based entirely on Swagger/OpenAPI specification (see [here](https://swagger.io/specification/)).\nThe hook produces specification based upon OAS 3.0.\n\n![](screenshot/swagger-doc.gif)\n\n\n## Installation\n```sh\n$ npm install sails-hook-swagger-generator --save\n```\n\n\n## Demo\nCopy the content of [generatedSwagger](test/fixtures/generatedSwagger.json) and paste it in [Swagger Online Editor](https://editor.swagger.io/).\n\n\n## Usage\nSimply by lifting your sails app `sails lift`, after lifting or starting the app,there should be `swagger.json` within **./swagger** folder.\n\n\u003e make sure ./swagger folder is already existing.\n\nCheck the **./swagger/swagger.json** for generated swagger documentation json, then head to [Swagger Editor](https://editor.swagger.io/).\n\n## Generated Output\n\nBy default, the Swagger Generator Sails Hook generates:\n1. Full automatic documentation for all Sails Blueprint routes;\n1. Documentation for all Sails\n   [actions2](https://sailsjs.com/documentation/concepts/actions-and-controllers#?actions-2)\n   actions with routes configured in `config/routes.js`; and\n1. Listing of all routes configured in `config/routes.js` (full details cannot be inferred\n   for custom routes without additional information being provided - see below).\n1. Creation of default tags for paths based upon Sails Model and Controller `globalId`'s.\n\n## Use with [Swagger UI](https://github.com/swagger-api/swagger-ui)\n\nSee [#28](https://github.com/theoomoregbee/sails-hook-swagger-generator/issues/28)\n\n## Adding/Customising Generated Output\n\nDocumentation detail and customisation of most aspects of the generated Swagger can be achieved by adding:\n1. Top-level configuration to `config/swaggergenerator.js`. This provides direct JSON\n   used as the template for the output Swagger/OpenAPI.\n1. Objects with the key `swagger` to custom route configuration, controller files, action\n   functions, model definitions and model attribute definitions. The `swagger` element must be of type\n   [SwaggerActionAttribute](./lib/interfaces.ts#L55) for actions (based on OpenApi.Operation)\n   or [SwaggerModelSchemaAttribute](./lib/interfaces.ts#L66) for model schemas (based on OpenApi.UpdatedSchema).\n1. JSDoc ([swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc)) `@swagger` comments\n   to controller/action files and model files.\n\nTop-level Swagger/OpenAPI definitions for `tags` and `components` may be added in all `swagger` objects\nabove and in all JSDoc `@swagger` documentation comments. This enables the definition of top-level elements.\n\nSee below for details.\n\n## Configurations\n\nIt comes with some default settings which can be overridden by creating `config/swaggergenerator.js`:\n```javascript\nmodule.exports['swagger-generator'] = {\n    disabled: false,\n    swaggerJsonPath: './swagger/swagger.json',\n    swagger: {\n        openapi: '3.0.0',\n        info: {\n            title: 'Swagger Json',\n            description: 'This is a generated swagger json for your sails project',\n            termsOfService: 'http://example.com/terms',\n            contact: {name: 'Theophilus Omoregbee', url: 'http://github.com/theo4u', email: 'theo4u@ymail.com'},\n            license: {name: 'Apache 2.0', url: 'http://www.apache.org/licenses/LICENSE-2.0.html'},\n            version: '1.0.0'\n        },\n        servers: [\n            { url: 'http://localhost:1337/' }\n        ],\n        externalDocs: {url: 'https://theoomoregbee.github.io/'}\n    },\n    defaults: {\n        responses: {\n            '200': { description: 'The requested resource' },\n            '404': { description: 'Resource not found' },\n            '500': { description: 'Internal server error' }\n        }\n    },\n    excludeDeprecatedPutBlueprintRoutes: true,\n    includeRoute: function(routeInfo) { return true; },\n    updateBlueprintActionTemplates: function(blueprintActionTemplates) { ... },\n    postProcess: function(specifications) { ... }\n};\n```\n\nNotes on the use of configuration:\n\n* `disabled` attribute is used to disable the module (e.g you may want to disable it on production).\n* `swaggerJsonPath` where to generate the `swagger.json` file to; defaults to `sails.config.appPath + '/swagger/swagger.json'`\n   and output file will not be written if empty/null/undefined (see `postProcess` below for alternate save mechanism).\n* `swagger` object is template for the Swagger/OpenAPI output. It defaults to the minimal content above.\n   Check Swagger/OpenAPI specification for more, in case you want to extend it.\n   Generally, this hook provides sensible defaults for as much as possible but you may\n   override them in this location or in any of the mechanisms explained below.\n* `defaults` object should contain the `responses` element; defaults to the above if not specified.\n* `excludeDeprecatedPutBlueprintRoutes` should\n  [deprecated](https://sailsjs.com/documentation/reference/blueprint-api/update#?notes) `PUT` blueprint\n  routes be excluded from generated Swagger output; defaults to `true`.\n* `includeRoute` function used to filter routes to be included in generated Swagger output; see advanced section below.\n* `updateBlueprintActionTemplates` allows customisation of the templates used to generate Swagger for blueprints; see advanced section below.\n* `postProcess` allows an alternate mechanism for saving and/or modification of the generated Swagger output before it is written to\n   the output file; see advanced section below.\n\n\n## Custom Route Configuration\n\nDocumentation detail and customisation of most aspects of the generated Swagger for\n[custom routes](https://sailsjs.com/documentation/concepts/routes/custom-routes) may be achieved by:\n\n1. Adding an object with the key `swagger` (must be of type [SwaggerActionAttribute](./lib/interfaces.ts#L55) for actions, based on OpenApi.Operation) to individual route configurations in `config/routes.js`.\n1. Adding an object with the key `swagger` (must be of type [SwaggerControllerAttribute](./lib/interfaces.ts#L76)) to the exports of a controller file, standalone action file or actions2 file.\n1. Adding an object with the key `swagger` (must be of type [SwaggerModelAttribute](./lib/interfaces.ts#L87)) to the exports of a model file.\n1. Adding JSDoc `@swagger` comments to Sails\n  [model files](https://sailsjs.com/documentation/concepts/models-and-orm/models),\n  [controller files](https://sailsjs.com/documentation/concepts/actions-and-controllers#?controllers),\n  [standalone action files](https://sailsjs.com/documentation/concepts/actions-and-controllers#?standalone-actions) or\n  [actions2 files](https://sailsjs.com/documentation/concepts/actions-and-controllers#?actions-2); specifically:\n    - JSDoc `@swagger` documentation under the `/{actionName}` path for the route (controllers/actions), or\n    - JSDoc `@swagger` documentation under the `/{blueprintAction}` path for the route (models), or\n    - JSDoc `@swagger` documentation under `tags` and `components` paths for adding to the top-level Swagger/OpenAPI definitions.\n\n\n### Custom Route Configuration in `config/routes.js`\n\nIf you want to add extra configuration to a route, it can be done via the `config/routes.js`, since Sails uses different [route targets](https://sailsjs.com/documentation/concepts/routes/custom-routes#?route-target), we can leverage the route object target to extend/override our swagger configuration by adding an object with a key `swagger`.\n\nFor example, in `config/routes.js`:\n```javascript\n{\n  'post /user/login': {\n    controller: 'UserController',\n    action: 'login',\n    swagger: {\n      summary: 'Authentication',\n      description: 'This is for authentication of any user',\n      tags: [ 'Tag Name' ],\n      requestBody: {\n        content: {\n          'application/json': {\n            schema: {\n              properties: {\n                email: { type: 'string' },\n                password: { type: 'string', format: 'password' }\n              },\n              required: [ 'email', 'password' ],\n            }\n          }\n        }\n      },\n      parameters: [{\n        in: 'query',\n        name: 'firstName',\n        required: true,\n        schema: { type: 'string' },\n        description: 'This is a custom required parameter'\n      }],\n      responses: {\n        '200': {\n          description: 'The requested resource',\n            content: {\n              'application/json': {\n                schema: {\n                  type: 'array',\n                  items: { '$ref': '#/components/schemas/someDataType' },\n                },\n              },\n            },\n        },\n        '404': { description: 'Resource not found' },\n        '500': { description: 'Internal server error' }\n      }\n    }\n  }\n}\n```\n\n### Custom Route Configuration in Controller or Action files\n\nDocumentation detail and customisation of most aspects of the generated Swagger may be added to\n[controller files](https://sailsjs.com/documentation/concepts/actions-and-controllers#?controllers),\n[standalone action files](https://sailsjs.com/documentation/concepts/actions-and-controllers#?standalone-actions) or\n[actions2 files](https://sailsjs.com/documentation/concepts/actions-and-controllers#?actions-2) as follows:\n\n1. Adding an object with the key `swagger` added to a controller file action function.\n1. Adding an object with the key `swagger` to the exports of a controller file, standalone\n   action file or actions2 file:\n   - For controller files, actions are referenced by adding objects keyed on `swagger.actions.{actionName}`\n     name. See [UserController.js](./api/controllers/UserController.js);\n   - For standalone action or actions2 files, placing content in the\n     `swagger.actions.{actionFileName|actions2FileName}` object. See\n     [actions2.js](./api/controllers/subdir/actions2.js)\n     ***Note**: `actionFileName|actions2FileName` must correspond to the filename*;\n   - For all controller/action files, adding per-action documentation to be\n     applied to **all** actions using the key `swagger.actions.allActions`\n     e.g. use this to apply common tags to all actions for a controller.\n   - Adding documentation under `tags` and `components` elements for adding to the\n     top-level Swagger/OpenAPI definitions. See example in either\n     [UserController.js](./api/controllers/UserController.js)\n     or [actions2.js](./api/controllers/subdir/actions2.js).\n1. Adding JSDoc `@swagger` comments to controller file, standalone action file or actions2 file:\n   - JSDoc `@swagger` documentation under the `/{actionName}` path for the controller file actions,\n   - JSDoc `@swagger` documentation under the `/{actionFileName|actions2FileName}` path for standalone action or actions2 files,\n   - JSDoc `@swagger` documentation under the `/allActions` path to be applied to **all** actions for the controller, or\n   - JSDoc `@swagger` documentation under `tags` and `components` paths for adding to the top-level Swagger/OpenAPI definitions.\n\nAn `exclude` property, set to `true`, may be added to any `swagger` element or `@swagger` JSDoc\naction documentation to exclude that action from the generated Swagger. See example in\n[NomodelController.js](api/controllers/NomodelController.js).\n\nThe Swagger definition for each action is merged in the order above to form the final\ndefinition, with `config/routes.js` taking highest precendence and **earlier** definitions\nabove taking precedence over later.\n\n#### For actions2 files:\n1. Inputs are parsed to generate parameter documentation.\n2. Exits are parsed to generate response documentation.\n3. Both may be customised/overridden by specifying parameters and/or responses in the `swagger` object\n   in actions2 file.\n4. Inputs may also add an object with the key `meta.swagger` to document the attributes\n   Swagger/OpenAPI **schema** associated with the input value. See example in\n   [actions2.js](./api/controllers/subdir/actions2.js).\n5. Inputs may be excluded from the generated Swagger by setting `meta.swagger.exclude` to `true`.\n6. Inputs may specify *where* the input should be included within the generated Swagger using the key\n   `meta.swagger.in`. The values `query`/`header`/`path`/`cookie` may be used to produce Swagger operation\n   parameters and the value `body` may be used to produce `requestBody` schema properties\n   (valid for PUT/POST/PATCH operations only).\n\nFor example, for a route configured as:\n```javascript\nmodule.exports.routes = {\n    '/api/v1/auth/tokens': 'AuthController.tokens',\n};\n```\n\nThe `tokens` action might be documented in a Controller `api/controllers/AuthController.js` as follows:\n```javascript\nfunction tokens(req, res) {\n    ...\n}\n\nmodule.exports = {\n    tokens: tokens,\n    swagger: {\n      actions: {\n        tokens: {\n            tags: [ 'Auth' ],\n            description: 'Route description...'\n        }\n      }\n      tags: [\n             {\n                name: 'Auth',\n                description: 'Module description ...',\n             }\n        ],\n      components: {\n        ...\n      }\n    }\n};\n```\n\nOr, alternately using JSDoc:\n```javascript\n/**\n * @swagger\n *\n * /tokens:\n *   description: Route description...\n *   tags:\n *     - Auth\n * tags:\n *   - name: Auth\n *     description: Module description...\n */\nfunction tokens(req, res) {\n    ...\n}\n\nmodule.exports = {\n    tokens: tokens\n};\n```\n\n## Blueprint Route Configuration\n\nDocumentation detail and customisation of most aspects of the generated Swagger for\n[blueprint routes](https://sailsjs.com/documentation/concepts/blueprints/blueprint-routes) may be achieved by:\n\n1. Adding an object with the key `swagger` to individual models e.g. `api/models/modelName.js`:\n   - Adding documentation to the model's Swagger **schema** using the key `swagger.modelSchema`\n     e.g. use this to apply detailed documentation via the `description` field;\n   - In additon to the model's schema, the key `swagger.modelSchema` may be used to specify\n     tag names (as a `string[]`) to be assigned all blueprint actions for the model.\n     This is a *non-standard* convenience function i.e. in Swagger/OpenAPI you need to\n     explicitly add tags to **each/every** OpenAPI.Operation;\n   - Adding per-action documentation by adding objects keyed on\n     `swagger.actions.{blueprintAction}` name;\n   - Adding action documentation to **all** actions using the key `swagger.actions.allActions`\n     e.g. use this to apply common `externalDocs` to all blueprint actions for the model; or\n   - Adding documentation under `swagger.tags` and `swagger.components` elements for adding to the top-level Swagger/OpenAPI definitions.\n1. Adding documentation-specific fields to model attributes (supports `description`, `moreInfoUrl` and `example`).\n   Note that applicable Sails [attributes](https://sailsjs.com/documentation/concepts/models-and-orm/attributes),\n   [automigrations](https://sailsjs.com/documentation/concepts/models-and-orm/attributes#?automigrations) and\n   [validations](https://sailsjs.com/documentation/concepts/models-and-orm/validations) are also parsed.\n1. Adding an object with the key `meta.swagger` to individual model attributes to document\n   the attributes Swagger/OpenAPI **schema**. See example in [Pet.js](./api/models/Pet.js).\n1. Adding JSDoc `@swagger` comments to model files:\n   - JSDoc `@swagger` documentation under the `/{globalId}` to add documentation to\n     the model's Swagger **schema** (or tags as noted above),\n   - JSDoc `@swagger` documentation under the `/{blueprintAction}` to add per-action\n     documentation for the\n     [model blueprint actions](https://sailsjs.com/documentation/concepts/blueprints/blueprint-actions),\n   - JSDoc `@swagger` documentation under the `/allActions` path to be applied to **all**\n     blueprint actions for the model, or\n   - JSDoc `@swagger` documentation under `tags` and `components` paths for adding to the\n     top-level Swagger/OpenAPI definitions.\n\nAn `exclude` property, set to `true`, may be added to any `swagger` element of `@swagger` JSDoc\naction documentation to exclude the model *completely* (exclude the **schema**) or a specific\nblueprint action from the generated Swagger. See example in [OldPet.js](api/models/OldPet.js).\n\nIndividual model attributes may be excluded from the generated Swagger by setting\n`meta.swagger.exclude` to `true`. See example in [Pet.js](api/models/Pet.js).\n\nOpenAPI 3 specifies the ***Any Type*** by the absence of the `type` property in a schema;\nthis may be achieved by setting a model attribute's `meta.swagger.type` value to `null`.\nSee example in [User.js](api/models/User.js).\n\nThe Swagger definition for each action is merged in the order above to form the final\ndefinition, with `config/routes.js` taking highest precendence and **earlier** definitions\nabove taking precedence over later.\n\nFor example, in a model `api/models/User.js`:\n\n```javascript\n/**\n * @swagger\n *\n * /User:\n *   tags:\n *     - Tag Name\n * /findone:\n *   externalDocs:\n *     url: https://docs.com/here\n */\nmodule.exports = {\n  attributes: {\n    uid: {\n      type: 'string',\n      example: '012345',\n      description: 'A unique identifier',\n    }\n  },\n  swagger: {\n    actions: {\n      create: { ... },\n    },\n    modelSchema: { ... },\n    tags: [...]\n    components: {...}\n  }\n};\n```\n\nNote that following parameters are added to the `components/parameters` if they are not\nprovided in `config/swaggergenerator.js` (expressed as OpenAPI references):\n\n```javascript\n[\n  { $ref: '#/components/parameters/WhereQueryParam' },\n  { $ref: '#/components/parameters/LimitQueryParam' },\n  { $ref: '#/components/parameters/SkipQueryParam' },\n  { $ref: '#/components/parameters/SortQueryParam' },\n  { $ref: '#/components/parameters/SelectQueryParam' },\n  { $ref: '#/components/parameters/PopulateQueryParam' },\n]\n```\n\nNote that when generating Swagger/OpenAPI documentation for blueprint routes, the hook also\ngenerates:\n\n1. Schemas for **models**, which may be referenced using the form `{ $ref: '#/components/schemas/modelName' }`.\n2. Parameters for model **primary keys**, which may be referenced using the form `{ $ref: '#/components/parameters/ModelPKParam-modelName' }`.\n\nThese may be re-used (referenced) if/as applicable within custom route documentation.\n\n\n## Handling Top-Level Swagger Defintions (Tags and Components)\n\nYou are able to add to the top-level Swagger/OpenAPI definitions for `tags` and `components` in all `swagger` objects\ndetailed above and in all JSDoc `@swagger` documention comments.\n\nAll `swagger` objects may contain the elements `tags` and `components`(*except the ones specified in `config.routes.js*) e.g.\n\n```javascript\n{\n  tags: [\n    {\n      name: 'Test Module',\n      description: 'Module description ...',\n      externalDocs: { url: 'https://docs.com/test' }\n    }\n  ],\n  components: {\n    schemas: {\n      test: { ... }\n    }\n  }\n}\n```\n\nSimilarly, JSDoc `@swagger` tags may define `tags` and `components`:\n\n```javascript\n/**\n * @swagger\n *\n * tags:\n *   - name: Test Module\n *     description: |\n *       Module description\n *       (continued).\n *\n *       Another paragraph.\n *\n *     externalDocs:\n *       url: https://docs.com/test\n *       description: Refer to these docs\n *\n * components:\n *   schemas:\n *     test:\n *       ...\n */\n```\n\n### Tags Handling\n\nTags are added to the top-level Swagger/OpenAPI definitions as follows:\n1. If a tags with the specified name **does not** exist, it is added.\n1. Where a tag with the specified name **does** exist, elements _of that tag_ that do not exist are added\n   e.g. `description` and `externalDocs` elements.\n\nNote that a final *clean-up* phase is run after processing, which performs the following:\n1. Removal of unreferenced tags; and\n2. Creation of tags referenced but are not defined.\n\n### Component Element Handling\n\nElements of components are added to the top-level Swagger/OpenAPI definitions as follows:\n1. Elements of the component definition reference (schemas, parameters, etc) are added where\n   they **do not exist**.\n1. Existing elements are **not** overwritten or merged.\n\nFor example, the element `components.schemas.pet` will be added as part of a merge process,\nbut the contents of multiple definitions of `pet` **will not** be merged.\n\nThe following elements (from the OpenAPI 3 specification) are handled:\n```javascript\nlet componentDefinitionReference = {\n    // Reusable schemas (data models)\n    schemas: {},\n    // Reusable path, query, header and cookie parameters\n    parameters: {},\n    // Security scheme definitions (see Authentication)\n    securitySchemes: {},\n    // Reusable request bodies\n    requestBodies: {},\n    // Reusable responses, such as 401 Unauthorized or 400 Bad Request\n    responses: {},\n    // Reusable response headers\n    headers: {},\n    // Reusable examples\n    examples: {},\n    // Reusable links\n    links: {},\n    // Reusable callbacks\n    callbacks: {},\n};\n```\n\n\n## Advanced Filtering/Processing of Generated Swagger\n\nThree mechanisms are provided to enable advancing filtering of the Swagger generation process:\n1. An `includeRoute()` function used to filter routes to be included in generated Swagger output.\n1. An `updateBlueprintActionTemplates()` function allows customisation of the templates used to generate Swagger for blueprints.\n1. A `postProcess()` function allows an alternate mechanism for saving and/or modification of the generated Swagger output before it is written to the output file.\n\nEach is configured in `config/swaggergenerator.js`.\n\n### Route Information\n\nThis hook parses all routes, custom and blueprint, before commencing the generation of the Swagger output.\nEach route is described by a `SwaggerRouteInfo` object\n(see defintion [here](./lib/interfaces.ts#L184)):\n\n```typescript\nexport interface SwaggerRouteInfo {\n  middlewareType: MiddlewareType; //\u003c one of action|blueprint\n\n  verb: HTTPMethodVerb; //\u003c one of all|get|post|put|patch|delete\n  path: string; //\u003c full Sails URL as per sails.getUrlFor() including prefix\n  variables: string[]; //\u003c list of ALL variables extracted from path e.g. `/pet/:id` --\u003e `id`\n  optionalVariables: string[]; //\u003c list of optional variables from path e.g. `/pet/:id?`\n\n  action: string; //\u003c either blueprint action (e.g. 'find') or action identity (e.g. 'subdir/reporting/run')\n  actionType: ActionType; //\u003c one of blueprint|shortcutBlueprint|controller|standalone|actions2|function\n  actions2Machine?: Sails.Actions2Machine; //\u003c for actionType === 'actions2', details of the action2 machine\n\n  model?: SwaggerSailsModel; //\u003c reference to Sails Model (blueprints only)\n  associationAliases?: string[]; //\u003c association attribute names (relevant blueprint routes only)\n\n  defaultTagName?: string; //\u003c default tag name for route, if any, based on Sails Model or Controller\n\n  swagger?: SwaggerActionAttribute; //\u003c per-route Swagger (OpenApi Operation)\n}\n```\n\nOther interfaces for models, `swagger` elements etc may be found in [interfaces.ts](./lib/interfaces.ts).\n\n\n### Route Filtering\n\nThe `includeRoute(routeInfo): boolean` function may be used to select which routes are included in the generated Swagger output.\n\nFor example:\n```javascript\nmodule.exports['swagger-generator'] = {\n  includeRoute: (routeInfo) =\u003e {\n    let c = routeInfo.controller;\n    if(!c) return true;\n    if(c.toLowerCase().startsWith('user')) return true;\n    return false;\n  }\n}\n```\n\n### Customising Blueprint Action Templates\n\nThe templates used for generating Swagger for each Sails blueprint action route may be\ncustomised / modified / added to using the `updateBlueprintActionTemplates` config option\ne.g. to support custom blueprint actions/routes.\n\nFor example:\n```javascript\nmodule.exports['swagger-generator'] = {\n  updateBlueprintActionTemplates: function(blueprintActionTemplates) {\n    blueprintActionTemplates.search = { ... };\n    return blueprintActionTemplates;\n  }\n}\n```\n\nThe `blueprintActionTemplates` object contains keys of the blueprint **action names**\nand values as per the following example (refer to the\n[source code](lib/type-formatter.js#L70) for the default templates):\n\n```javascript\nlet blueprintActionTemplates = {\n  findone: {\n    summary: 'Get {globalId} (find one)',\n    description: 'Look up the **{globalId}** record with the specified ID.',\n    externalDocs: {\n      url: 'https://sailsjs.com/documentation/reference/blueprint-api/find-one',\n      description: 'See https://sailsjs.com/documentation/reference/blueprint-api/find-one'\n    },\n    parameters: [\n      'primaryKeyPathParameter', // special case; filtered and substituted during generation phase\n      { $ref: '#/components/parameters/LimitQueryParam' },\n    ],\n    resultDescription: 'Responds with a single **{globalId}** record as a JSON dictionary',\n    notFoundDescription: 'Response denoting **{globalId}** record with specified ID **NOT** found',\n    // if functions, each called with (blueprintActionTemplate, routeInfo, pathEntry)\n    modifiers: ['addSelectQueryParam', exampleModifierFunctionRef],\n  },\n  ...\n};\n```\n\nNote that:\n1. For summary and description strings the value `{globalId}` is replaced with the applicable Sails model value.\n1. Parameters values are Swagger definitions, with the exception of the *special* string value\n   `primaryKeyPathParameter`, which may be used to include a reference to a model's primary key.\n1. Modifiers are used to apply custom changes to the generated Swagger, noting that:\n   - String values are predefined in `generatePaths()` (refer to the [source code](lib/generators.js#L246));\n     valid  modifiers are:\n     - `addPopulateQueryParam`\n     - `addSelectQueryParam`\n     - `addOmitQueryParam`\n     - `addModelBodyParam`\n     - `addModelBodyParamUpdate`\n     - `addResultOfArrayOfModels`\n     - `addAssociationPathParam`\n     - `addAssociationFKPathParam`\n     - `addAssociationResultOfArray`\n     - `addResultOfModel`\n     - `addResultNotFound`\n     - `addResultValidationError`\n     - `addFksBodyParam`\n     - `addShortCutBlueprintRouteNote`\n   - Functions are called as `func(blueprintActionTemplate, routeInfo, pathEntry, tags, components)`\n     where\n     - `blueprintActionTemplate` the blueprint action template (see above) to which the modifier relates\n     - `routeInfo` the route information object (see above) for which the Swagger is being generated\n     - `pathEntry` the generated Swagger path entry to be modified\n     - `tags` the generated Swagger **tag** definitions to be modified/extended\n     - `components` the generated Swagger **component** definitions to be modified/extended\n\n### Post-processing Generated Swagger Output\n\nThe final generated Swagger output may be post-processed before it is written to\nthe output file using a post-processing function specified as the `postProcess` config option.\n\nFor situations where saving the generated swagger documentation JSON to a file is\nnot desired/appropriate, the `postProcess` config option may be used to specify\nan alternate save mechanism.\n\nNote that if `swaggerJsonPath` config option is empty/null/undefined the output file will not be written.\n\nFor example:\n```javascript\nmodule.exports['swagger-generator'] = {\n  postProcess: function(specifications) {\n    let sch = specifications.components.schemas;\n    Object.keys(sch).map(k =\u003e {\n      sch[k].description = sck[k].description.toUpperCase();\n    });\n  }\n}\n```\n\n\n## Testing\n\n* Clone this repository\n\n* Install all development dependencies\n\n```sh\n npm install\n```\n* Then run test\n\n```sh\nnpm test\n```\n\n## Contribute\n\nFork this repo and push in your ideas.\nDo not forget to add a bit of test(s) of what value you adding.\n* stick to conventional commit message [here](https://conventionalcommits.org/) or read more [angular commit](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit) pattern\n* While developing, you can run the below command to start nodemon watch too run linting and testing on `.ts` changes\n\n```sh\nnpm run dev\n```\n\n## Changelog\n\nSee the different releases [here](https://github.com/theo4u/sails-hook-swagger-generator/releases)\n\n## License\n\nMIT License (MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheoomoregbee%2Fsails-hook-swagger-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheoomoregbee%2Fsails-hook-swagger-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheoomoregbee%2Fsails-hook-swagger-generator/lists"}