This repository contains a starting point for documenting an API with OpenAPI and displaying the documentation using Framna Docs.
The OpenAPI specification is split across multiple files in the src/ directory and bundled into a single file for distribution.
Read more about this workflow in the Framna Docs wiki: Working with Large Specs.
The repository contains the following files and folders.
| File/Folder | Description |
|---|---|
| src/ | Source directory containing the split OpenAPI specification files. |
| src/openapi.yml | The main OpenAPI specification file that references other components. |
| src/paths/ | Directory containing individual path/endpoint definitions. |
| src/schemas/ | Directory containing reusable schema definitions. |
| openapi-bundle.yml | The bundled OpenAPI specification generated from the src files. |
| bundle.sh | Script to bundle the split OpenAPI files into a single specification. |
| lint.sh | Script to lint the OpenAPI specification. |
| .framna-docs.yml | A configuration file that specifies the project name and icon to show on Framna Docs. For more information, see the documentation of Framna Docs. |
| icon.png | The icon displayed on Framna Docs. |
| .spectral.yml | A configuration file for the open-source Spectral linter that can be used to validate the OpenAPI specification. |
| .github/workflows/lint.yml | A workflow that lints the OpenAPI specification in pull requests using the Spectral linter. |
| .githooks/ | Directory containing Git hooks for the repository. |
| .githooks/pre-push | A pre-push hook that automatically runs the bundle script and ensures the bundled file is up to date before pushing. |
To enable the pre-push hook that automatically bundles the OpenAPI spec before pushing:
git config core.hooksPath .githooksThis ensures the openapi-bundle.yml file is always up to date when pushing changes.
To modify the API specification, edit files in the src/ directory:
- Add or modify endpoints in src/paths/
- Add or modify schemas in src/schemas/
- Update the main specification in src/openapi.yml
After making changes, run bundle.sh to generate the bundled openapi-bundle.yml file.