Getting Started

Want to get started immediately? Check out the getting started guide or check out the demo to see the plugin in action.

Features

A Starlight plugin to generate documentation from OpenAPI/Swagger specifications.

• Support for Swagger 2.0, OpenAPI 3.0 and OpenAPI 3.1 specifications.
• Support for local and remote schemas.
• Configurable sidebar label and sidebar group collapsing.

License

Licensed under the MIT License, Copyright © HiDeoo.

See LICENSE for more information.

starlight-openapi

0.19.1

Patch Changes

• #115 6c37f8e Thanks @HiDeoo! - Prevents a potential build error for OpenAPI schemas containing incorrectly formatted enum values.

0.19.0

Minor Changes

• #112 64e03d9 Thanks @HiDeoo! - Adds support for specifying custom sidebar groups for individual OpenAPI schemas.

  When generating documentation for multiple schemas, this allows you to place the generated documentation pages for each schema anywhere in the Starlight sidebar, even in different sidebar groups.

  See the "Sidebar groups" section in the documentation for more information.

0.18.0

Minor Changes

• #109 6de8f2b Thanks @HiDeoo! - Respects Starlight convention to generate URLs with a trailing slash when using the trailingSlash: 'ignore' Astro configuration option (the default) as many common hosting providers redirect to URLs with a trailing slash by default.

Patch Changes

• #109 6de8f2b Thanks @HiDeoo! - Fixes a sidebar link generation issue when using the Astro trailingSlash configuration option set to always.

0.17.0

Minor Changes

• #103 4179569 Thanks @HiDeoo! - Adds support for callbacks in OpenAPI 3 specs.

0.16.1

Patch Changes

• #100 1b00fcf Thanks @cruzdanilo! - Fixes an issue preventing numeric enum values from being rendered.

0.16.0

Minor Changes

• #96 933cc5c Thanks @HiDeoo! - ⚠️ BREAKING CHANGE: The minimum supported version of Starlight is now version 0.34.0.

  Please use the @astrojs/upgrade command to upgrade your project:

  npx @astrojs/upgrade

• #96 933cc5c Thanks @HiDeoo! - Adds clickable anchor links to headings which respects the Starlight markdown.headingLinksSection configuration option.

0.15.0

Minor Changes

• #94 9b95bca Thanks @HiDeoo! - Adds support for schemas using version 3.0.4 of the OpenAPI specification by updating the OpenAPI and Swagger API definitions parser used internally.

0.14.4

Patch Changes

• #90 6953670 Thanks @HiDeoo! - Fixes potential sidebar link issues when using the Astro base option.

0.14.3

Patch Changes

• #88 d2cdf30 Thanks @HiDeoo! - Fixes a compatibility issue with some other Starlight plugins due to how the sidebar entries for the generated pages were being created.

0.14.2

Patch Changes

• #86 ecc5bb3 Thanks @HiDeoo! - Fixes syntax highlighting issues for many examples where the code block language was not properly inferred.

0.14.1

Patch Changes

• #83 dc88650 Thanks @HiDeoo! - Ensures property titles are rendered when provided in a schema.

0.14.0

Minor Changes

• #80 d6175bc Thanks @HiDeoo! - Adds a new sidebar.operations.sort configuration option to configure the sorting method for the operation sidebar links.

  The current behavior to sort the operation sidebar links in the order they appear in the OpenAPI document is preserved by default. Setting this option to 'alphabetical' will sort the operation sidebar links alphabetically.

• #80 d6175bc Thanks @HiDeoo! - Deprecates the sidebar label, collapsed, and sidebarMethodBadges options in favor of a new sidebar option object.

  The previous options are still supported for backward compatibility, but they will be removed in a future release.

  starlightOpenAPI([
    {
      base: 'api',
      schema: '../schemas/api-schema.yaml',
  -   label: 'My API',
  -   collapsed: false,
  -   sidebarMethodBadges: true,
  +   sidebar: {
  +     label: 'My API',
  +     collapsed: false,
  +     operations: { badges: true },
  +   },
    },
  ])

• #80 d6175bc Thanks @HiDeoo! - Adds a new sidebar.tags.sort configuration option to configure the sorting method for the tag sidebar groups.

  The current behavior to sort the tag sidebar groups in the order they appear in the OpenAPI document is preserved by default. Setting this option to 'alphabetical' will sort the tag sidebar groups alphabetically.

• #80 d6175bc Thanks @HiDeoo! - Adds a new sidebar.operations.labels configuration option to define whether the operation sidebar labels should use the operation ID or summary.

  The current behavior to use the operation summary and fall back to the operation ID if no summary is provided is preserved by default. Setting this option to 'operationId' will always use the operation ID as the operation sidebar label.

Patch Changes

• #80 d6175bc Thanks @HiDeoo! - Fixes a rendering issue for model definition properties using nested allOf properties.

• #80 d6175bc Thanks @HiDeoo! - Fixes a syntax highlighting issue for response examples defined at the object-level in a reference of the components section.

0.13.0

Minor Changes

• #75 52dd833 Thanks @HiDeoo! - ⚠️ BREAKING CHANGE: The minimum supported version of Starlight is now version 0.32.0.

  Please use the @astrojs/upgrade command to upgrade your project:

  npx @astrojs/upgrade

0.12.1

Patch Changes

• #73 beeb586 Thanks @HiDeoo! - Adds astro as a peer dependency to prevent potential build errors in monorepos with hoisting disabled.

0.12.0

Minor Changes

• #70 b6679d7 Thanks @HiDeoo! - Improves formatting of query parameter examples based on the style and explode property values and the RFC 6570 URI template specification.

0.11.0

Minor Changes

• #67 194dfe7 Thanks @HiDeoo! - Adds a new sidebarMethodBadges schema configuration option to display badges next to sidebar operation links with the associated HTTP method.

0.10.0

Minor Changes

• #63 b19e249 Thanks @HiDeoo! - Adds overview pages for operations grouped by tags defined with a description or externalDocs fields displaying the tag's information.

0.9.0

Minor Changes

• #58 f91f2f4 Thanks @HiDeoo! - Adds support for Astro v5, drops support for Astro v4.

  ⚠️ BREAKING CHANGE: The minimum supported version of Starlight is now 0.30.0.

  Please follow the upgrade guide to update your project.