{"id":14986573,"url":"https://github.com/giddyinc/doctopus","last_synced_at":"2025-04-11T20:32:12.412Z","repository":{"id":19522023,"uuid":"87209565","full_name":"giddyinc/doctopus","owner":"giddyinc","description":null,"archived":false,"fork":false,"pushed_at":"2023-02-28T04:28:53.000Z","size":1852,"stargazers_count":24,"open_issues_count":5,"forks_count":1,"subscribers_count":28,"default_branch":"master","last_synced_at":"2024-04-14T06:18:32.002Z","etag":null,"topics":["api","apis","docs","documentation","open-api","openapi-specification","schema","swagger","swagger-mapper","swagger-ui"],"latest_commit_sha":null,"homepage":null,"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/giddyinc.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-04T16:21:20.000Z","updated_at":"2024-06-19T17:34:46.848Z","dependencies_parsed_at":"2024-06-19T17:34:38.297Z","dependency_job_id":"6588cad6-b88e-425a-9bb6-429dbe45b353","html_url":"https://github.com/giddyinc/doctopus","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giddyinc%2Fdoctopus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giddyinc%2Fdoctopus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giddyinc%2Fdoctopus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giddyinc%2Fdoctopus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giddyinc","download_url":"https://codeload.github.com/giddyinc/doctopus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248476416,"owners_count":21110276,"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","apis","docs","documentation","open-api","openapi-specification","schema","swagger","swagger-mapper","swagger-ui"],"created_at":"2024-09-24T14:13:09.669Z","updated_at":"2025-04-11T20:32:07.393Z","avatar_url":"https://github.com/giddyinc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n[![NPM version][npm-image]][npm-url]\n[![Build Status][travis-image]][travis-url]\n\u003c!-- [![Dependency Status][daviddm-image]][daviddm-url] --\u003e\n[![codecov](https://codecov.io/gh/giddyinc/doctopus/branch/master/graph/badge.svg)](https://codecov.io/gh/giddyinc/doctopus)\n\n# doctopus\n\nNobody likes writing docs. So to make it better, we wrote doctopus; a fluent pluggable Swagger spec builder enabling docs to be built quickly and maintained automatically.\n\n![alt tag](octopus1.jpg)\n\nThe doctopus API provides heavy syntactic sugar over Swagger enabling re-use of common libraries and components for documentation composition.\n\nWhen used in conjunction with sister libraries doctopus faciliates schema reuse for persistence, validation, and documentation reducing maintenance overhead and increasing consistency.\n\n## Overview\n\nWay more documentation to come.\n\nIt is important to note that doctopus implements a mutable API enabling reuse of common variables and parameters to make documenting common routes easier. It is recommended to create a single instance per route file and clear params (`doc.clearParams()`) when they change. \n\n## Installation\n\n```sh\n$ npm install --save doctopus\n```\n\n### Example Configuration\n\n```js\n\nconst app = require('express')();\nconst doctopus = require('doctopus');\n\nconst docs = new doctopus.DocBuilder();\nconst docFactory = new doctopus.Doc();\n\ndocs.set('title', 'My Express App');\n\ndocs.add('/swagger', docFactory.get()\n    .group('Documentation')\n    .description('Gets a Swagger Specification')\n    .summary('Swagger')\n    .onSuccess(200, {\n        description: 'Swagger Spec',\n        schema: Doc.object()\n    })\n    .build());\n\napp.get('/swagger', (req, res) =\u003e res.send(docs.build()));\napp.listen('3000');\n\n```\n\n#### Decorator API\n```ts\n\nimport { \n    get, \n    route, \n    group, \n    param, \n    response, \n    Doc, \n    DocBuilder,\n} from 'doctopus';\n\n// set default for all controller methods\n@group('Cats')\nclass CatCtrl {\n\n    // http get request\n    @get\n    // set route\n    @route('/cats/{id}')\n    // override group of a specific method\n    @group('Orders')\n    public findOne(req, res) {\n        res.send({});\n    }\n\n    @get\n    @route('/cats')\n    // add a param\n    @param({\n        in: 'query',\n        type: 'string',\n        name: 'name',  \n    })\n    // declare response\n    @response({\n        description: 'All Cats',\n        schema: Doc.object(), // schema, see schema api\n    })\n    public findAll(req, res) {\n        res.send([]);\n    }\n}\n\nconst docs = new DocBuilder();\n\n// docBuilder instance will read the docs\ndocs.use(CatCtrl);\n\n```\n\n## Advanced Usage\n\nDoctopus was designed with automation and re-usability in mind. To leverage automatic doc generation, we recommend using two packages that we've found to be helpful. \n\n\n- [joi-to-swagger](https://www.npmjs.com/package/joi-to-swagger) - Joi Validation Object to Swagger Mapper\n  - For API inputs, joi is an excellent validation framework which can help define sync endpoint validation and with doctopus, you can also define your documentation using the same schemas.\n- [mongoose-to-swagger](https://www.npmjs.com/package/mongoose-to-swagger) - Mongoose Model to Swagger Mapper\n  - For API outputs, often times API endpoints simply return JSON representations of mongoose models.\n  Doctopus allows you to simply reference the mongoose model (Doc.model('name')) and have the swagger schema automatically generated.\n\nAfter you've registered your mongoose models...\n\n```js\n\nconst joi = require('joi');\nconst j2s = require('joi-to-swagger');\nconst m2s = require('mongoose-to-swagger');\n\n// ...\n\nconst docs = new doctopus.DocBuilder();\nconst definitions = {\n  // you can define custom definitions in line or reference from another file if you choose\n  'Cat': {\n      'id': 'Cat',\n      'properties': {\n          'name': {\n              'type': 'string'\n          }\n      }\n  }\n};\n\n// automatically register // namespace all mongoose models\nfor(const i in mongoose.models) {\n    definitions[`mongoose|${i}`] = m2s(mongoose.models[i]);\n}\n\nconst joiSchemas = {\n    Cat: joi.object().keys({\n      name: joi.string()\n    })\n};\n\nObject.keys(joiSchemas).forEach(k =\u003e {\n    definitions[`joi|${k}`] = j2s(joiSchemas[k]).swagger;\n});\n\n// enable Reflection in doctopus api (Doc.pick('RegisteredModel', 'Property')))\ndoctopus.Doc.setDefinitions(definitions);\n\n// add definitions to swagger definitions\ndocs.addDefinitions(definitions);\n\n```\n\n#### Parameter Groups\n\n```js\n\nconst group = {\n  accessToken: {\n    name: 'accessToken',\n    description: 'Client Token',\n    in: 'query',\n    required: false,\n    type: 'string'\n  },\n  fields: {\n    name: 'fields',\n    description: 'Fields you want returned',\n    in: 'query',\n    required: false,\n    type: 'string'\n  }\n};\n\ndoctopus.paramGroup('public', group);\n\n// later\nDoc.paramGroup('public');\n\n```\n\n## Resources\n- [Helpful Tutorial](http://mherman.org/blog/2016/05/26/swagger-and-nodejs)\n- [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc) - annotation helper\n- [Official Swagger Documentation](http://swagger.io/docs/)\n\n\n## Contributing\nWe look forward to seeing your contributions!\n\n\n## License\n\nMIT © [Ben Lugavere](http://benlugavere.com/)\n\n[npm-image]: https://badge.fury.io/js/doctopus.svg\n[npm-url]: https://npmjs.org/package/doctopus\n[travis-image]: https://travis-ci.org/giddyinc/doctopus.svg?branch=master\n[travis-url]: https://travis-ci.org/giddyinc/doctopus\n[daviddm-image]: https://david-dm.org/giddyinc/doctopus.svg?theme=shields.io\n[daviddm-url]: https://david-dm.org/giddyinc/doctopus\n[coveralls-image]: https://coveralls.io/repos/giddyinc/doctopus/badge.svg\n[coveralls-url]: https://coveralls.io/r/giddyinc/doctopus\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiddyinc%2Fdoctopus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiddyinc%2Fdoctopus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiddyinc%2Fdoctopus/lists"}