{"id":20423593,"url":"https://github.com/divinrkz/swaggiffy","last_synced_at":"2025-04-12T18:41:49.993Z","repository":{"id":41503481,"uuid":"378576031","full_name":"divinrkz/swaggiffy","owner":"divinrkz","description":"A zero config opensource tool for documenting your Node.js Express APIs endpoints.","archived":false,"fork":false,"pushed_at":"2023-10-25T11:52:00.000Z","size":557,"stargazers_count":43,"open_issues_count":4,"forks_count":9,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-31T07:01:36.384Z","etag":null,"topics":["documentation","documentation-generator","documentation-tool","javascript","rest-api","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/divinrkz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"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":"2021-06-20T06:34:20.000Z","updated_at":"2025-01-05T14:02:52.000Z","dependencies_parsed_at":"2024-09-24T04:01:12.675Z","dependency_job_id":"f5dbac3d-def8-4e77-9503-e52c83efdd80","html_url":"https://github.com/divinrkz/swaggiffy","commit_stats":null,"previous_names":["divinirakiza/swaggiffy"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divinrkz%2Fswaggiffy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divinrkz%2Fswaggiffy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divinrkz%2Fswaggiffy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divinrkz%2Fswaggiffy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/divinrkz","download_url":"https://codeload.github.com/divinrkz/swaggiffy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248322600,"owners_count":21084336,"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":["documentation","documentation-generator","documentation-tool","javascript","rest-api","swagger","typescript"],"created_at":"2024-11-15T07:07:02.395Z","updated_at":"2025-04-12T18:41:49.965Z","avatar_url":"https://github.com/divinrkz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SWAGGIFY\n\nSwaggiffy is a zero config opensource tool for documenting your Node.js Express APIs and is built on top of Swagger. It is designed to be easy to use and simple, with the goal that anyone can read it. \u003cbr\u003e\n\n## Features\n\n-   Automated Swagger Schema Registry.\n-   Automated Swagger API Definition Registry.\n-   Automatic Swagger file rendering.\n-   Clean and Simple Config file.\n-   Supports both OpenAPI 2 and OpenAPI 3.\n-   Supports for Typescript Classes.\n-   Support for Mongoose ORM Schema Objects.\n-   Support for Swagger YAML and JSON.\n-   Rich CLI.\n-   Built on top on Express and Swagger.\n\nAnd more ...\n\n## Get started\n\n### Install\n\n```bash\nnpm i swaggiffy #npm\nyarn add swaggiffy #yarn\npnpm add swaggiffy #pnpm\n```\n\n### Swaggify Configuration\n\nSwaggify creates a clean and simple configuration file. In addition, it create a swagger definition file,\nto your preffered path specified in the configuration file.\n\nThis is will generate both `swaggiffy.config.json` and `swagger/swagger.json` files.\n\n```bash\nnpx swaggiffy init -p PORT\n```\n\nGenerate the config file only.\n\n```bash\nnpx swaggiffy generate:config\n```\n\nGenerate the spec file only.\n\n```bash\nnpx swaggiffy generate:spec\n```\n\n### Instantiate Swaggify\n\nIn your main .js or .ts file.\n\n```js\nconst { Swaggiffy } = require('swaggiffy'); // Using require\nimport { Swaggiffy } from 'swaggiffy'; // Using import\n```\n\nBuild Swaggiffy with your express app.\n\n```js\nnew Swaggiffy().setupExpress(app).swaggiffy();\n```\n\n### Using Swaggiffy\n\n#### Schema Registry\n\nTo register a schema\n\n```js\nimport { registerSchema, registerSchemas } from 'swaggiffy';\n\n\nregisterSchema('Model Name 1', modelObj1); // for plain Js objects\nregisterSchema('Model Name 2', modelObj2, { orm: 'mongoose' }); // for mongoose model\nregisterSchema('Model Name 2', modelObj3, { orm: 'sequelize' }); // for sequelize model\n\nregisterSchemas([  {'Model Name 1', modelObj1 }, {'Model Name 2', modelObj2, { orm: 'mongoose' }} ]); // for multiple schemas\n```\n\nFor classes use\n\n```js\nimport { Schema } from 'swaggiffy';\n\n@Schema('Model')\nclass Model {\n    property1 = '';\n    property2 = '';\n    property3 = '';\n}\n```\n\n#### API Definition Registry\n\nWe generate API Definition from Express Routers.\n\n`tags`: Tags are swagger groupings\n`mappedSchema`: Maps the desired schema registered in swagger to your API Definition.\n`basePath`: Base Paths specifies the route for your router.\n\n```js\nimport { registerDefinition, registerDefinitions } from 'swaggiffy';\n\nregisterDefinition(router, { tags: 'Products', mappedSchema: 'Product', basePath: '/products' });\n\nregisterDefinitions([\n    router1,\n    { tags: 'Products', mappedSchema: 'Product', basePath: '/products' },\n    router2,\n    { tags: 'Users', mappedSchema: 'User', basePath: '/user' },\n]);\n```\n\n#### Run the App\n\n```bash\nnode app.js\n```\n\nWith nodemon we need to exclude files\n\n```bash\nnodemon --ignore '*swagger.json' app.js\n```\n\nor create a `nodemon.json` file with\n\n```json\n{\n    \"ignore\": [\"*swagger.json\"]\n}\n```\n\nTada!, Now access `localhost:PORT/api-docs` to see swagger 😁.\n\n### DEMO\n\nCheckout this repository for demo and additional examples.\n[Swaggiffy Samples](https://github.com/divinirakiza/swaggify-samples)\n\n### CONTRIBUTIONS\n\nYou are welcome for contributions. Please read our [CONTRIBUTING.md](https://github.com/divinirakiza/swaggiffy/blob/main/CONTRIBUTING.md) file.\n\n### MAINTAINERS\n\n-   Divin Irakiza ([@divinirakiza](https://github.com/divinirakiza))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdivinrkz%2Fswaggiffy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdivinrkz%2Fswaggiffy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdivinrkz%2Fswaggiffy/lists"}