-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #18 from HiDeoo/hd-plugin
- Loading branch information
Showing
36 changed files
with
2,311 additions
and
2,337 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| { | ||
| "eslint.experimental.useFlatConfig": true, | ||
| "eslint.validate": [ | ||
| "javascript", | ||
| "javascriptreact", | ||
| "typescript", | ||
| "typescriptreact", | ||
| "html", | ||
| "vue", | ||
| "markdown", | ||
| "astro" | ||
| ] | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,7 +2,7 @@ | |
| "name": "starlight-openapi-docs", | ||
| "version": "0.4.0", | ||
| "license": "MIT", | ||
| "description": "Astro integration for Starlight to generate documentation from OpenAPI/Swagger specifications.", | ||
| "description": "Starlight plugin to generate documentation from OpenAPI/Swagger specifications.", | ||
| "author": "HiDeoo <[email protected]> (https://hideoo.dev)", | ||
| "type": "module", | ||
| "scripts": { | ||
|
|
@@ -14,12 +14,11 @@ | |
| "lint": "prettier -c --cache . && eslint . --cache --max-warnings=0" | ||
| }, | ||
| "dependencies": { | ||
| "@astrojs/starlight": "0.11.0", | ||
| "astro": "3.2.3", | ||
| "@astrojs/starlight": "0.19.0", | ||
| "astro": "4.4.0", | ||
| "sharp": "0.33.2", | ||
| "shiki": "0.14.4", | ||
| "starlight-openapi": "workspace:*", | ||
| "starlight-package-managers": "0.1.0" | ||
| "starlight-package-managers": "0.3.0" | ||
| }, | ||
| "engines": { | ||
| "node": ">=18.14.1" | ||
|
|
@@ -29,6 +28,7 @@ | |
| "sideEffects": false, | ||
| "keywords": [ | ||
| "starlight", | ||
| "plugin", | ||
| "openapi", | ||
| "swagger", | ||
| "documentation", | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,127 @@ | ||
| --- | ||
| title: Configuration | ||
| description: An overview of all the configuration options supported by the Starlight OpenAPI plugin. | ||
| --- | ||
|
|
||
| The Starlight OpenAPI plugin can be configured inside the `astro.config.mjs` configuration file of your project: | ||
|
|
||
| ```js {11} | ||
| // astro.config.mjs | ||
| import starlight from '@astrojs/starlight' | ||
| import { defineConfig } from 'astro/config' | ||
| import starlightOpenAPI, { openAPISidebarGroups } from 'starlight-openapi' | ||
|
|
||
| export default defineConfig({ | ||
| integrations: [ | ||
| starlight({ | ||
| plugins: [ | ||
| starlightOpenAPI([ | ||
| // Configuration options go here. | ||
| ]), | ||
| ], | ||
| title: 'My Docs', | ||
| }), | ||
| ], | ||
| }) | ||
| ``` | ||
|
|
||
| ## Plugin configuration | ||
|
|
||
| The Starlight OpenAPI plugin accepts an array of objects where each object represents a configuration for a specific OpenAPI/Swagger schema. | ||
|
|
||
| A configuration object can have the following properties: | ||
|
|
||
| ### `base` (required) | ||
|
|
||
| **Type:** `string` | ||
|
|
||
| The base path containing the generated documentation, e.g. `'api/petstore'`. | ||
|
|
||
| ### `schema` (required) | ||
|
|
||
| **Type:** `string` | ||
|
|
||
| The OpenAPI/Swagger schema path or URL. | ||
|
|
||
| ### `label` | ||
|
|
||
| **Type:** `string` | ||
|
|
||
| The generated documentation sidebar group label. | ||
|
|
||
| ### `collapsed` | ||
|
|
||
| **Type:** `boolean` | ||
|
|
||
| Wheter the generated documentation sidebar group should be collapsed by default or not. | ||
|
|
||
| ## Multiple schemas | ||
|
|
||
| You can generate documentation for multiple OpenAPI/Swagger schemas by passing multiple objects to the plugin configuration. | ||
|
|
||
| ```js {11-21} | ||
| // astro.config.mjs | ||
| import starlight from '@astrojs/starlight' | ||
| import { defineConfig } from 'astro/config' | ||
| import starlightOpenAPI, { openAPISidebarGroups } from 'starlight-openapi' | ||
|
|
||
| export default defineConfig({ | ||
| integrations: [ | ||
| starlight({ | ||
| plugins: [ | ||
| starlightOpenAPI([ | ||
| { | ||
| base: 'api/petstore', | ||
| label: 'My API', | ||
| schema: '../schemas/api-schema.yaml', | ||
| }, | ||
| { | ||
| base: 'api/1password', | ||
| label: '1Password Connect', | ||
| schema: | ||
| 'https://raw.githubusercontent.com/APIs-guru/openapi-directory/gh-pages/v2/specs/1password.local/connect/1.5.7/openapi.yaml', | ||
| }, | ||
| ]), | ||
| ], | ||
| title: 'My Docs', | ||
| }), | ||
| ], | ||
| }) | ||
| ``` | ||
|
|
||
| ## Sidebar groups | ||
|
|
||
| The `openAPISidebarGroups` export can be used in your Starlight [sidebar configuration](https://starlight.astro.build/reference/configuration/#sidebar) to add the generated documentation sidebar group to the sidebar. | ||
|
|
||
| ```js {24-25} "{ openAPISidebarGroups }" | ||
| // astro.config.mjs | ||
| import starlight from '@astrojs/starlight' | ||
| import { defineConfig } from 'astro/config' | ||
| import starlightOpenAPI, { openAPISidebarGroups } from 'starlight-openapi' | ||
|
|
||
| export default defineConfig({ | ||
| integrations: [ | ||
| starlight({ | ||
| plugins: [ | ||
| // Generate the OpenAPI documentation pages. | ||
| starlightOpenAPI([ | ||
| { | ||
| base: 'api', | ||
| label: 'My API', | ||
| schema: '../schemas/api-schema.yaml', | ||
| }, | ||
| ]), | ||
| ], | ||
| sidebar: [ | ||
| { | ||
| label: 'Guides', | ||
| items: [{ label: 'Example Guide', link: '/guides/example/' }], | ||
| }, | ||
| // Add the generated sidebar group to the sidebar. | ||
| ...openAPISidebarGroups, | ||
| ], | ||
| title: 'My Docs', | ||
| }), | ||
| ], | ||
| }) | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| --- | ||
| title: Getting Started | ||
| description: Learn how to generate documentation from OpenAPI/Swagger specifications using the Starlight OpenAPI plugin. | ||
| --- | ||
|
|
||
| import PackageManagers from '../../components/PackageManagers.astro' | ||
|
|
||
| A [Starlight](https://starlight.astro.build) plugin to generate documentation from OpenAPI/Swagger specifications. | ||
|
|
||
| - Support for [Swagger 2.0](https://swagger.io/specification/v2/), [OpenAPI 3.0](https://swagger.io/specification/v3/) and [OpenAPI 3.1](https://swagger.io/specification/) specifications. | ||
| - Support for local and remote schemas. | ||
| - Configurable sidebar label and sidebar group collapsing. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| You will need to have a Starlight website set up. | ||
| If you don't have one yet, you can follow the ["Getting Started"](https://starlight.astro.build/getting-started) guide in the Starlight docs to create one. | ||
|
|
||
| ## Install the plugin | ||
|
|
||
| Starlight OpenAPI is a Starlight [plugin](https://starlight.astro.build/reference/plugins/). | ||
| Install it using your favorite package manager: | ||
|
|
||
| <PackageManagers pkg="starlight-openapi" /> | ||
|
|
||
| ## Configure the plugin | ||
|
|
||
| The Starlight OpenAPI plugin can be configured in your Starlight [configuration](https://starlight.astro.build/reference/configuration/#plugins) in the `astro.config.mjs` file. | ||
|
|
||
| ```diff lang="js" | ||
| // astro.config.mjs | ||
| import starlight from '@astrojs/starlight' | ||
| import { defineConfig } from 'astro/config' | ||
| +import starlightOpenAPI, { openAPISidebarGroups } from 'starlight-openapi' | ||
|
|
||
| export default defineConfig({ | ||
| integrations: [ | ||
| starlight({ | ||
| + plugins: [ | ||
| + // Generate the OpenAPI documentation pages. | ||
| + starlightOpenAPI([ | ||
| + { | ||
| + base: 'api', | ||
| + label: 'My API', | ||
| + schema: '../schemas/api-schema.yaml', | ||
| + }, | ||
| + ]), | ||
| + ], | ||
| sidebar: [ | ||
| { | ||
| label: 'Guides', | ||
| items: [{ label: 'Example Guide', link: '/guides/example/' }], | ||
| }, | ||
| + // Add the generated sidebar group to the sidebar. | ||
| + ...openAPISidebarGroups, | ||
| ], | ||
| title: 'My Docs', | ||
| }), | ||
| ], | ||
| }) | ||
| ``` | ||
|
|
||
| The Starlight OpenAPI plugin behavior can be tweaked using various [configuration options](/configuration). |
Oops, something went wrong.