@scalar/openapi-to-markdown 0.5.43 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @scalar/openapi-to-markdown
 
+## 0.6.0
+
+### Minor Changes
+
+- [#10169](https://github.com/scalar/scalar/pull/10169): Render scoped operation, tag, model, webhook, and introduction pages in Markdown and HTML while preserving referenced schemas and inherited context.
+
+## 0.5.44
+
 ## 0.5.43
 
 ## 0.5.42

package/README.md

@@ -73,8 +73,8 @@ const operationMarkdownByPointer = await createMarkdownFromOpenApi(content, {
 You use the package with any Node.js framework. Here is an example for [Hono](https://hono.dev/):
 
 ```ts
-import { Hono } from 'hono'
 import { createMarkdownFromOpenApi } from '@scalar/openapi-to-markdown'
+import { Hono } from 'hono'
 
 // Generate Markdown from an OpenAPI document
 const markdown = await createMarkdownFromOpenApi(content)
@@ -102,8 +102,8 @@ transforms the HTML to Markdown then.
 So if you'd like to have a really light-weight HTML API Reference, here you are:
 
 ```ts
-import { Hono } from 'hono'
 import { createHtmlFromOpenApi } from '@scalar/openapi-to-markdown'
+import { Hono } from 'hono'
 
 // Generate HTML from an OpenAPI document
 const html = await createHtmlFromOpenApi(content)
@@ -139,3 +139,33 @@ We are API nerds. You too? Let's chat on Discord: <https://discord.gg/scalar>
 ## License
 
 The source code in this repository is licensed under [MIT](https://github.com/scalar/scalar/blob/main/LICENSE).
+
+## Individual reference pages
+
+Both `createMarkdownFromOpenApi` and `createHtmlFromOpenApi` accept the same options. Choose one selector per call:
+
+```ts
+await createMarkdownFromOpenApi(content, { tag: 'pets' })
+await createMarkdownFromOpenApi(content, { model: 'Pet' })
+await createMarkdownFromOpenApi(content, {
+  webhook: { name: 'petCreated', method: 'post' },
+})
+await createMarkdownFromOpenApi(content, { introduction: true })
+await createHtmlFromOpenApi(content, { operation: { operationId: 'getUser' } })
+```
+
+- **Operation:** One operation, effective parameters, servers and authentication, its tags, and referenced component schemas. Existing path/method, operation ID, and JSON pointer selectors still work. Methods are case insensitive.
+- **Tag:** Tag metadata and all path operations with that exact tag, plus their context and schema dependencies. A tag used only by operations is supported. A declared tag with no operations renders its metadata. Operations with multiple tags appear once, with only the selected tag shown.
+- **Model:** One component schema and its referenced schemas. Primitive, array, composed, and recursive models use the shared schema renderer.
+- **Webhook:** One operation selected by its exact OpenAPI webhook name and method, including parameters, payload and responses. The name is a label, not a delivery URL.
+- **Introduction:** API title, versions, description, contact, license, terms of service, servers and global authentication requirements. No operations, tags, models or webhooks.
+
+Selected pages retain API title, versions and description. They exclude unrelated reference content. Operation servers override path servers, which override document servers. Operation security overrides document security, including `security: []` for anonymous access. Parameter overrides use the parameter name and location. Required schemas are collected after reference resolution, so dependencies remain available even when their original section is omitted.
+
+Omitting options, or passing `{}`, renders the whole document. OpenAPI 2.0 inputs are migrated before selection: use definition names with `model`. Webhooks require OpenAPI 3.1 or later.
+
+### Errors and limitations
+
+Invalid, combined, or missing selectors reject the returned promise with an error. Duplicate operation IDs are ambiguous and list matching paths and methods; use a path/method selector instead. Duplicate tag declarations are also rejected. Names are case sensitive. Operation JSON pointers must target `/paths/{path}/{method}`, with an optional leading `#` and standard `~0`/`~1` escaping.
+
+Selection does not add support for every OpenAPI or JSON Schema keyword. Callbacks are not selectable pages. External references follow the existing workspace loader behavior. Recursive schema expansion stops on a repeated ancestor, with a depth limit of ten as a fallback. Shared dependencies have one component section, but may also appear inline where used. Authentication lists alternatives separately; schemes within one requirement must be used together.

package/dist/components/MarkdownReference.vue.d.ts

@@ -1,4 +1,4 @@
-import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.1/strict/openapi-document';
+import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
 type MarkdownDocument = Partial<OpenApiDocument> & Pick<OpenApiDocument, 'openapi' | 'info'>;
 type __VLS_Props = {
     content: MarkdownDocument;

package/dist/components/MarkdownReference.vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MarkdownReference.vue.d.ts","sourceRoot":"","sources":["../../src/components/MarkdownReference.vue"],"names":[],"mappings":"AA4kBA,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,8DAA8D,CAAA;AAQrE,KAAK,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,GAC9C,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,MAAM,CAAC,CAAA;AAuC3C,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAC;AAouBF,QAAA,MAAM,YAAY,kSAEhB,CAAC;wBACkB,OAAO,YAAY;AAAxC,wBAAyC"}
+{"version":3,"file":"MarkdownReference.vue.d.ts","sourceRoot":"","sources":["../../src/components/MarkdownReference.vue"],"names":[],"mappings":"AAqnBA,OAAO,KAAK,EACV,eAAe,EAOhB,MAAM,8DAA8D,CAAA;AASrE,KAAK,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,GAC9C,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,MAAM,CAAC,CAAA;AA2C3C,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAC;AA20BF,QAAA,MAAM,YAAY,kSAEhB,CAAC;wBACkB,OAAO,YAAY;AAAxC,wBAAyC"}

package/dist/components/Schema.vue.d.ts

@@ -1,7 +1,8 @@
-import type { MaybeRefSchemaObject } from '@scalar/workspace-store/schemas/v3.1/strict/schema';
+import type { MaybeRefSchemaObject } from '@scalar/workspace-store/schemas/v3.2/strict/schema';
 type __VLS_Props = {
     schema: MaybeRefSchemaObject;
     depth?: number;
+    ancestors?: unknown[];
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;

package/dist/components/Schema.vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Schema.vue.d.ts","sourceRoot":"","sources":["../../src/components/Schema.vue"],"names":[],"mappings":"AAiZA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oDAAoD,CAAA;AAI9F,KAAK,WAAW,GAAG;IACjB,MAAM,EAAE,oBAAoB,CAAA;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAC;AAqhBF,QAAA,MAAM,YAAY,kSAEhB,CAAC;wBACkB,OAAO,YAAY;AAAxC,wBAAyC"}
+{"version":3,"file":"Schema.vue.d.ts","sourceRoot":"","sources":["../../src/components/Schema.vue"],"names":[],"mappings":"AAiaA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oDAAoD,CAAA;AAE9F,KAAK,WAAW,GAAG;IACjB,MAAM,EAAE,oBAAoB,CAAA;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,EAAE,CAAA;CACtB,CAAC;AA+iBF,QAAA,MAAM,YAAY,kSAEhB,CAAC;wBACkB,OAAO,YAAY;AAAxC,wBAAyC"}

package/dist/components/Security.vue.d.ts

@@ -0,0 +1,9 @@
+import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+type __VLS_Props = {
+    requirements?: OpenApiDocument['security'];
+    schemes?: NonNullable<OpenApiDocument['components']>['securitySchemes'];
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;
+//# sourceMappingURL=Security.vue.d.ts.map

package/dist/components/Security.vue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Security.vue.d.ts","sourceRoot":"","sources":["../../src/components/Security.vue"],"names":[],"mappings":"AA0DA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAGnG,KAAK,WAAW,GAAG;IACjB,YAAY,CAAC,EAAE,eAAe,CAAC,UAAU,CAAC,CAAA;IAC1C,OAAO,CAAC,EAAE,WAAW,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAA;CACxE,CAAC;AAoGF,QAAA,MAAM,YAAY,kSAEhB,CAAC;wBACkB,OAAO,YAAY;AAAxC,wBAAyC"}

package/dist/create-markdown-from-openapi.d.ts

@@ -1,5 +1,5 @@
 import type { HttpMethod } from '@scalar/helpers/http/http-methods';
-import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.1/strict/openapi-document';
+import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
 type AnyDocument = OpenApiDocument | Record<string, unknown> | string;
 export type { HttpMethod };
 export type OperationSelector = {
@@ -10,8 +10,19 @@ export type OperationSelector = {
 } | {
     pointer: string;
 };
+/** Select one reference page, or omit selectors for the whole document. */
 export type OpenApiRenderOptions = {
-    operation?: OperationSelector;
+    [Key in keyof PageSelectors]: Partial<Record<Exclude<keyof PageSelectors, Key>, never>> & Pick<PageSelectors, Key>;
+}[keyof PageSelectors] | Partial<Record<keyof PageSelectors, never>>;
+type PageSelectors = {
+    operation: OperationSelector;
+    tag: string;
+    model: string;
+    webhook: {
+        name: string;
+        method: HttpMethod | Uppercase<HttpMethod>;
+    };
+    introduction: true;
 };
 export declare function createHtmlFromOpenApi(input: AnyDocument, options?: OpenApiRenderOptions): Promise<string>;
 export declare function createMarkdownFromOpenApi(content: AnyDocument, options?: OpenApiRenderOptions): Promise<string>;

package/dist/create-markdown-from-openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-markdown-from-openapi.d.ts","sourceRoot":"","sources":["../src/create-markdown-from-openapi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAMnE,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,8DAA8D,CAAA;AAanH,KAAK,WAAW,GAAG,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAA;AACrE,YAAY,EAAE,UAAU,EAAE,CAAA;AAC1B,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC,CAAA;CAC3C,GACD;IACE,WAAW,EAAE,MAAM,CAAA;CACpB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACL,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,CAAC,EAAE,iBAAiB,CAAA;CAC9B,CAAA;AAwMD,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,oBAAoB,mBA8C7F;AAED,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,oBAAoB,mBAEnG"}
+{"version":3,"file":"create-markdown-from-openapi.d.ts","sourceRoot":"","sources":["../src/create-markdown-from-openapi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAOnE,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,8DAA8D,CAAA;AAanH,KAAK,WAAW,GAAG,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAA;AACrE,YAAY,EAAE,UAAU,EAAE,CAAA;AAC1B,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC,CAAA;CAC3C,GACD;IACE,WAAW,EAAE,MAAM,CAAA;CACpB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACL,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAC5B;KACG,GAAG,IAAI,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC;CACnH,CAAC,MAAM,aAAa,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,aAAa,EAAE,KAAK,CAAC,CAAC,CAAA;AAE/C,KAAK,aAAa,GAAG;IACnB,SAAS,EAAE,iBAAiB,CAAA;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC,CAAA;KAAE,CAAA;IACrE,YAAY,EAAE,IAAI,CAAA;CACnB,CAAA;AA6ZD,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,oBAAoB,mBA2C7F;AAED,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,oBAAoB,mBAEnG"}