{"id":14156084,"url":"https://github.com/openapi-contrib/openapi3-generator","last_synced_at":"2025-08-06T02:31:37.988Z","repository":{"id":44844707,"uuid":"142300673","full_name":"openapi-contrib/openapi3-generator","owner":"openapi-contrib","description":"Use your API OpenAPI 3 definition to generate code, documentation, and literally anything you need.","archived":false,"fork":false,"pushed_at":"2023-03-14T17:26:06.000Z","size":139,"stargazers_count":90,"open_issues_count":22,"forks_count":27,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-28T01:33:47.219Z","etag":null,"topics":["oasv3","openapi","openapi3"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openapi-contrib.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":"2018-07-25T13:02:15.000Z","updated_at":"2024-10-19T11:35:38.000Z","dependencies_parsed_at":"2024-06-18T22:48:14.355Z","dependency_job_id":null,"html_url":"https://github.com/openapi-contrib/openapi3-generator","commit_stats":null,"previous_names":["fmvilas/openapi3-generator"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi-contrib%2Fopenapi3-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi-contrib%2Fopenapi3-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi-contrib%2Fopenapi3-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi-contrib%2Fopenapi3-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openapi-contrib","download_url":"https://codeload.github.com/openapi-contrib/openapi3-generator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228829049,"owners_count":17978141,"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":["oasv3","openapi","openapi3"],"created_at":"2024-08-17T08:05:12.389Z","updated_at":"2024-12-09T03:31:01.471Z","avatar_url":"https://github.com/openapi-contrib.png","language":"JavaScript","funding_links":[],"categories":["others"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eOpenAPI 3 Generator\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  Use your API OpenAPI 3 definition to generate code, documentation, and literally anything you need.\n\u003c/p\u003e\n\n## Install\n\nTo use it from the CLI:\n\n```bash\nnpm install -g openapi3-generator\n```\n\n## Requirements\n\n* Node.js v7.6+\n\n## Usage\n\n### From the command-line interface (CLI)\n\n```bash\n  Usage: og [options] \u003copenapiFileOrURL\u003e \u003ctemplate\u003e\n\n\n  Options:\n\n    -V, --version                  output the version number\n    -o, --output \u003coutputDir\u003e       directory where to put the generated files (defaults to current directory)\n    -t, --templates \u003ctemplateDir\u003e  directory where templates are located (defaults to internal templates directory)\n    -b, --basedir \u003cbaseDir\u003e        directory to use as the base when resolving local file references (defaults to OpenAPI file directory)\n    -h, --help                     output usage information\n```\n\n#### Examples\n\nThe shortest possible syntax:\n```bash\nog openapi.yaml markdown\n```\n\nSpecify where to put the generated code:\n```bash\nog -o ./my-docs openapi.yaml markdown\n```\n\n## Templates\n\n### Creating your own templates\nTemplates are the sources where the result will be generated from. There are already some templates\nyou can use to generate code and documentation.\n\nThe files in your template can be of the following types:\n1. Static: This kind of files will be simply copied to the output directory.\n2. Templates: This kind of files will be compiled using [Handlebars](http://handlebarsjs.com/), and copied to the output directory.\n3. Path templates: This kind of files will be compiled using [Handlebars](http://handlebarsjs.com/), but it will generate one file per OpenAPI path.\n\nAssuming we have the following OpenAPI Spec:\n```yaml\nopenapi: \"3.0.0\"\ninfo:\n  version: 1.0.0\n  title: OpenAPI Petstore\n  license:\n    name: MIT\nservers:\n  - url: http://petstore.openapi.io/v1\npaths:\n  /pet:\n    get:...\n    post:...\n  /pet/{petId}:\n    get:...\n  /user/login:\n    post:...\n  /user/{username}:\n    get:...\n    put:...\n    delete:...\n...\n```\nAnd some template files like this:\n```\n|- index.js            // This file contains static code, e.g. starting a webserver and including ./api/index.js\n|+ api/\n |- index.js.hbs       // This is a static template, it contains placeholders that will be filled in, e.g. includes for each file in routes\n |+ routes/\n  |- $$path$$.route.js.hbs      // This file will be generated for each operation and contains skeleton code for each method for an operation.\n  |+ $$path$$/                  // This folder will also be generated for each operation.\n    |- route.js.hbs             // This is another example of an operation file.\n```\nThe first important thing to notice here is the variable notation in `$$path$$.route.js.hbs`. It will be replaced by the name of the path.\n\nThis example also shows `$$path$$` used in a folder name - the generated folder names here will replace $$path$$ with\nthe name of the path (in kebab-case).\n\nIn this example the generated directory structure will be like this:\n```\n|- index.js            // This file still contains static code like before.\n|+ api/\n |- index.js           // This file will now e.g. have included the two files in routes.\n |+ routes/\n  |- pet.route.js      // This file contains the code for methods on pets.\n  |                    // (e.g. getPet, postPet, getPetByPetId).\n  |- user.route.js     // This file will contain the code for methods on users.\n  |                    // (e.g. postUserLogin, getUserByUsername, putUserByUsername, deleteUserByUsername).\n  |+ pet/\n   | - route.js        // this file also contains the code for methods on pets.\n  |+ user/\n   | - route.js        // this file also contains the code for methods on users.\n```\n\n### Template file extensions\nYou can (optionally) name your template files with `.hbs` extensions, which will be removed when writing the generated\nfile. e.g. `index.js.hbs` writes `index.js`. `index.js` would also write to `index.js`, if you prefer to omit the hbs\nextension.\n\nThe only case where the `.hbs` extension isn't optional would be if you are writing handlebars templates with the\ntemplates. In that case the the template would need the extension `.hbs.hbs`. `usertpl.hbs.hbs` writes `usertpl.hbs`\n(but `usertpl.hbs` as a source would write `usertpl` with no extension).\n\n### Template file content\nThe generator passes the OpenAPI spec to template files, so all information should be available there.\nIn addition to that, the code generator adds a bit [more data](#data-passed-to-handlebars-templates) that can be helpful.\n\n#### Examples:\n##### Dynamically require files in JavaScript\n```mustache\n{{#each @root.openapi.endpoints}}\nconst {{.}} = require('./routes/{{.}}.route.js')\n{{/each}}\n```\nwill produce (using the OAS Spec example from above):\n```js\nconst pet = require('./routes/pet.route.js')\nconst user = require('./routes/user.route.js')\n```\n\n### Data passed to Handlebars templates\n| Param | Type | Description |\n| --- | --- | --- |\n|openapi|object|The OpenAPI spec.|\n|openapi.endpoints| object | All first level endpoints (e.g  `pet` and `user`) |\n\n### Custom handlebars helpers\nIf your template needs Handlebars helpers, you can define them in a directory called `.helpers` inside your template.\n\nCheck out some examples in the [markdown](./templates/markdown/.helpers) template.\n\n### Using handlebars partials\nIf you want to use partials in your template, define them in a directory called `.partials` inside your template.\n\nCheck out some examples in the [markdown](./templates/markdown/.partials) template.\n\n\u003e The name of the partial will be obtained from the file name, converted to camel case. So, for instance, if the file name is `my-partial.js`, you can use the partial with `{{\u003e myPartial}}`.\n\n## Authors\n\n* Fran Méndez ([@fmvilas](http://twitter.com/fmvilas))\n* Richard Klose ([@richardklose](http://github.com/richardklose))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenapi-contrib%2Fopenapi3-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenapi-contrib%2Fopenapi3-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenapi-contrib%2Fopenapi3-generator/lists"}