{"id":13593436,"url":"https://github.com/dgarcia360/openapi-boilerplate","last_synced_at":"2025-04-11T23:20:54.759Z","repository":{"id":38216152,"uuid":"239108172","full_name":"dgarcia360/openapi-boilerplate","owner":"dgarcia360","description":"📘 Multi-file boilerplate for Open API Specification","archived":false,"fork":false,"pushed_at":"2025-03-31T16:55:06.000Z","size":2631,"stargazers_count":390,"open_issues_count":5,"forks_count":89,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-04T00:06:39.921Z","etag":null,"topics":["api-documentation","documentation-boilerplate","openapi","openapi3","swagger"],"latest_commit_sha":null,"homepage":"https://dgarcia360.github.io/openapi-boilerplate/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dgarcia360.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-08T10:23:15.000Z","updated_at":"2025-03-17T07:02:17.000Z","dependencies_parsed_at":"2024-01-16T21:42:57.206Z","dependency_job_id":"f4a5d5a0-e4a8-4ad0-ba66-9ebab696392f","html_url":"https://github.com/dgarcia360/openapi-boilerplate","commit_stats":{"total_commits":90,"total_committers":3,"mean_commits":30.0,"dds":"0.37777777777777777","last_synced_commit":"5f804d99c40b17532e01aa85969ef5abf7cc1d59"},"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgarcia360%2Fopenapi-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgarcia360%2Fopenapi-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgarcia360%2Fopenapi-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgarcia360%2Fopenapi-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dgarcia360","download_url":"https://codeload.github.com/dgarcia360/openapi-boilerplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248493033,"owners_count":21113186,"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","documentation-boilerplate","openapi","openapi3","swagger"],"created_at":"2024-08-01T16:01:20.293Z","updated_at":"2025-04-11T23:20:54.740Z","avatar_url":"https://github.com/dgarcia360.png","language":"Shell","funding_links":[],"categories":["others","Shell"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cdiv style=\"display:inline-block;vertical-align: middle;\"\u003e\n      \u003cimg src=\"docs/header.png\" width=\"550\"/\u003e\n  \u003c/div\u003e\n\u003c/h1\u003e\n\n[![OpenAPI linter](https://github.com/dgarcia360/openapi-boilerplate/actions/workflows/linter.yaml/badge.svg)](https://github.com/dgarcia360/openapi-boilerplate/actions/workflows/linter.yaml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n# OpenAPI boilerplate\n\nA starter template for **OpenAPI Specification** (OAS) projects.\n\nThis project splits the [Swagger Petstore](https://petstore.swagger.io/) example from the official documentation into smaller files. It also adds handy commands to build, lint, and preview the OpenAPI document from the terminal.\n\nYou can use this template to guide the organization of your project. Either if you want to create a new OpenAPI document from scratch or if you already have it defined. \n\n## Features\n\n* 📝 Write OpenAPI definitions in different files.\n* 🔀 Combine all files with [redocly-cli](https://github.com/Redocly/redocly-cli).\n* ✅ Validate and lint the OpenAPI document with [stoplightio/spectral](https://github.com/stoplightio/spectral).\n* ✨ Publish reference docs with [Redoc](https://github.com/Redocly/redoc) \u0026 GitHub Pages.\n\n## Why?\n\nWhen I used to document APIs following the OpenAPI spec, I always ended up with documents of thousands of lines, which were a nightmare to maintain.\n\nFor this reason, I explored how to split OpenAPI documents. Jump over to my [blog](https://davidgarcia.dev/posts/how-to-split-open-api-spec-into-multiple-files/) to learn more about the process. Based on my research, I created this opinionated template to define, test, and publish modular OpenAPI projects.\n\nOrganizing your project effectively offers significant benefits. Splitting a large OpenAPI spec into multiple files makes it easier to manage and maintain. It also makes the documentation process more efficient and less overwhelming. I've found that with this structure, other devs are more inclined to contribute and suggest changes to the documentation, as it feels more approachable and less intimidating.\n\n## Getting started\n\n### Requirements\n\n* Node.js 16 (current)\n\n### Installation\n\n1. Clone the repository.\n\n    ```\n    git clone https://github.com/dgarcia360/openapi-boilerplate.git\n    ```\n\n2. Install the project dependencies.\n\n    ```\n    npm install\n    ```\n\n3. Edit `openapi.yaml` to fit your API definition. If you’re not familiar with the OpenAPI Specification, read [Getting started with OAS](https://swagger.io/solutions/getting-started-with-oas/) first.\n\n## Useful commands\n\nThe project will build, lint, and preview the OpenAPI document from the terminal, with the following commands:\n\n### Build\n\nThe command bundles the spec as one `.yaml` file.\n\n```\nnpm run build\n```\n\nThe minified document is stored in `_build/openapi.yaml`.\n\n### Test\n\nThe command checks if the document follows the OpenAPI 3.0 Specification.\n\n```\nnpm run test\n```\n\n### Preview\n\nThe command builds a docs site so that you can view the rendering on your local browser.\n\n```\nnpm run preview\n```\n\nThe server starts on http://127.0.0.1:8080.\n\nThe site is generated with [ReDoc](https://github.com/Redocly/redoc).\nHere's a preview of a site generated with this command: [Swagger Petstore Reference Documentation](https://dgarcia360.github.io/openapi-boilerplate/).\n\n## Ready-to-use workflows\n\nThe project uses [GitHub Actions](https://github.com/features/actions) for Continuous Integration (CI).\n\nOn every new pull request, the OpenAPI document is linted with [spectral](https://github.com/stoplightio/spectral). If there are changes that introduce errors, the bot will highlight them replying to the pull request.\n\nWhen the default branch (e.g. `master`) receives an update, a workflow automatically publishes the API reference documentation site to GitHub Pages.\n\nSee `.github/workflows` to customize the available workflows. If you don't plan to use GitHub to host your spec or prefer to keep docs private, delete the `.github` folder.\n\n## Contributing\n\nContributions are welcome and appreciated! \nIf you want to enhance the boilerplate, please read [CONTRIBUTING.md](CONTRIBUTING.md) file first.\n\n## License\n\nCopyright (c) 2019-present David Garcia ([@dgarcia360](https://davidgarcia.dev)). Licensed under the [MIT License](LICENSE.md).\n\nThe PetStore example used is derived from [OAI/OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml), Copyright The Linux Foundation, Licensed under the [Apache License, Version 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdgarcia360%2Fopenapi-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdgarcia360%2Fopenapi-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdgarcia360%2Fopenapi-boilerplate/lists"}