About openapi formatter
Format an OpenAPI or Swagger document as clean, indented YAML or JSON, and convert between the two.
YAML or JSON
YAML is easier for people to read and edit. JSON is easier for programs to process. Both hold the same information.
A worked example
A one-line JSON specification can be converted to indented YAML, which is easier to review in a pull request. Converting from YAML to JSON gives the form that some tools and generators require. The content stays the same.
Tips
- Keep one source of truth and generate the other format.
- Sort keys consistently so diffs are small.
- Validate after formatting to catch accidental edits.
Reusable pieces
Move repeated schemas into components and refer to them with $ref, so that the specification stays short and each definition lives in one place.
Review changes
Use a diff tool on the formatted files to see what changed between API versions before you publish a new release.
