909fb471ca
* feat: Add Vale configuration and rules * docs: Fix top-level files to match Vale rules * docs: Vale updates for the commands docs * docs: apply Vale updates to the decorator docs * docs: Update guides to match Vale rules * docs: update rules and other content to meet Vale standards * docs: add Vale link and information to CONTRIBUTING * feat: Add GitHub action for Vale * docs: minor editing to readme.md * docs: minor editing to the changelog.md file * docs: minor edits to the join.md file in commands folder * docs: minor edits to lint.md file in the commands directory * docs: minor edit to the login.md file in the commands directory * docs: minor edits to the preview.md file in the commands directory * docs: minor edits to push.md file in the comands directory * docs: minor edits to the info-description-override.md file in the decorators directory * docs: minor edits to the configure-rules.md file in the guides directory * docs: minor edits to custom-plugin.md file in the resources directory * docs: minor editing to the no-http-verbs-in-paths.md file in the rules directory --------- Co-authored-by: Heather Cloward <heathercloward@gmail.com>
2.6 KiB
How to use openapi-starter
The openapi-starter is a Redocly project that you can clone to your own GitHub account to more easily manage API definition files either as single files or multiple files.
It automatically creates the required folder structure and generates a basic OpenAPI definition file, which is great if you're new to API reference docs.
Although you can create your own folder structure, we recommend letting openapi-starter set it up initially (you can always make changes later). The folder structure is also key when using the OpenAPI split and bundle commands, which are used to split up large definitions for easier maintenance, and compile the constituent files back into a single file when you're ready to publish your API reference docs.
Step 1: Copy the openapi-starter project
- Go to https://github.com/Redocly/openapi-starter.
- Select Use this template.
- You’ll be asked to create a new repository from openapi-starter.
- Give your repo a meaningful name (e.g. redocly-openapi-starter).
- Choose whether you want it to be public or private.
- Leave the Include all branches option deselected.
- Select Create repository from template.
The project is copied to your GitHub account. It is independent and not linked to the source.
Step 2: Clone the project
Clone the project to your local machine so you can use it with Redocly CLI.
Step 3: Work with OpenAPI
By default, there is a root directory (openapi) that contains a sample API definition file (openapi.yaml). The sample file is already split into its constituent parts, which are contained in the code_samples, components and paths folders.
Just starting out with API docs?
Use our openapi.yaml file to explore Redocly CLI. We suggest you run some basic commands like lint, bundle and split to practice.
Got your own API definition file?
You can add your files straight into the openapi folder and use the existing sub-folders when splitting them up for easier maintenance (split command) and compiling them back into a single file (bundle) for publishing out. Be aware that the more definitions stored in the openapi folder, the more cluttered the sub-folders. But hey, if you like clutter then go for it!
Prefer things more orderly? Create new root folders to store each definition. When you run the split command in Redocly CLI for a specified definition file, the sub-folders are automatically created under the root and populated with the constituent parts of your main definition file.