@dogsbay/format-openapi 0.2.0-beta.14 → 0.2.0-beta.141

package/dist/cli.d.ts

@@ -1,3 +1,2 @@
 import type { FormatPlugin } from "@dogsbay/types";
 export declare const plugin: FormatPlugin;
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -10,7 +10,9 @@ export const plugin = {
         return parseOpenApiSpec(source, {
             hrefPrefix: typeof opts.hrefPrefix === "string" ? opts.hrefPrefix : undefined,
             section: typeof opts.section === "string" ? opts.section : undefined,
+            reservedSlugs: Array.isArray(opts.reservedSlugs)
+                ? opts.reservedSlugs.filter((s) => typeof s === "string")
+                : undefined,
         });
     },
 };
-//# sourceMappingURL=cli.js.map

package/dist/code-samples.d.ts

@@ -13,4 +13,3 @@ import type { CodeSample } from "./types.js";
  * use `x-code-samples` (kebab). Honour both.
  */
 export declare function resolveCodeSamples(operation: any, method: string, path: string, baseUrl: string): CodeSample[];
-//# sourceMappingURL=code-samples.d.ts.map

package/dist/code-samples.js

@@ -39,6 +39,16 @@ function readVendorSamples(operation) {
             sample.label = entry.label;
         samples.push(sample);
     }
+    // A `label` only disambiguates when it VARIES across samples (e.g. "Sync" vs
+    // "Async" for two Python samples). Speakeasy sets every sample's label to the
+    // SDK method name (e.g. "banPartner"), which is identical across languages and
+    // makes every tab read the same — drop it so the tab falls back to the
+    // language name (Python, Go, …), the API-docs convention.
+    const distinctLabels = new Set(samples.map((s) => s.label));
+    if (samples.length > 1 && distinctLabels.size === 1) {
+        for (const s of samples)
+            delete s.label;
+    }
     return samples;
 }
 function generateCodeSamples(method, path, baseUrl) {
@@ -65,4 +75,3 @@ function generateCodeSamples(method, path, baseUrl) {
         },
     ];
 }
-//# sourceMappingURL=code-samples.js.map

package/dist/core.d.ts

@@ -0,0 +1,111 @@
+import type { ExportPage, Heading, NavItem, TreeNode } from "@dogsbay/types";
+export { findSpec, specCandidates, type SpecLookup } from "./spec-path.js";
+export interface ParseOpenApiOptions {
+    /** When the importer wants nav hrefs to start with this prefix. */
+    hrefPrefix?: string;
+    /** Sub-path within the namespace for emitted pages, e.g. "api". */
+    section?: string;
+    /**
+     * First URL segments the site already uses for something else: the
+     * source's own `/<name>/` prefix, the base path, taxonomy indexes. A tag
+     * (or untagged operation) with one of these slugs is renamed (`api-2`),
+     * because a site-root link to `/api/list-things` on a source published
+     * under `/api/` reads as already prefixed and is never rewritten.
+     */
+    reservedSlugs?: readonly string[];
+}
+/**
+ * A dereferenced spec (`prepareSpec`) as a page per operation, a page per tag
+ * and an info page, with their nav: for a spec that IS the source.
+ */
+export declare function specToPages(spec: any, options?: ParseOpenApiOptions): {
+    pages: ExportPage[];
+    nav: NavItem[];
+};
+/**
+ * Spec text → object. JSON is read natively; YAML needs a parser passed in
+ * (`yaml`'s `parse`, js-yaml's `load`), so a host that has one does not
+ * bundle a second.
+ */
+export declare function parseSpecText(text: string, parseYaml?: (text: string) => unknown): unknown;
+/**
+ * A parsed spec → the dereferenced OpenAPI 3 document every function here
+ * reads. Swagger 2.0 is upgraded to OpenAPI 3 first: everything below reads
+ * the 3.x shape (`requestBody`, response `content`, `servers`), so a 2.0
+ * spec parsed without the upgrade lost every body parameter and response
+ * schema while still producing plausible-looking pages. Canonical's Anbox
+ * Cloud API specs are 2.0.
+ */
+export declare function prepareSpec(parsed: unknown, label?: string): Promise<any>;
+/**
+ * Prepared specs by path, each parsed and dereferenced once however many
+ * pages embed it. `read` returns the file's text; failures are cached too,
+ * so a broken spec is reported per page without being parsed again.
+ */
+export declare function createSpecCache(read: (path: string) => string | Promise<string>, parseYaml?: (text: string) => unknown): {
+    get(path: string): Promise<any>;
+    readonly size: number;
+};
+/** What a value over its bound is shown as. */
+export declare const VALUE_TOO_LARGE = "(not shown: too large)";
+/**
+ * The summary and description, with a sentence the generator broke in two
+ * put back together. drf-yasg makes the summary from a docstring's first
+ * LINE and the description from the rest, so a sentence that wraps reads
+ * "…retrieve the list of" + a paragraph "activity streams.". A summary with
+ * no closing punctuation, followed by a description that starts in lower
+ * case, takes the description's first paragraph when that ends the
+ * sentence and the summary is long enough to be a wrapped line. Only plain text is moved:
+ * the summary is shown as text, so Markdown in the continuation would show
+ * its syntax.
+ */
+export declare function summaryAndDescription(summary: string | undefined, description: string | undefined): {
+    summary?: string;
+    description?: string;
+};
+export interface OpenApiEmbedOptions {
+    level?: number;
+    /** Ids the page already uses: the embed's headings get others. */
+    usedIds?: Iterable<string>;
+    /**
+     * One operation instead of the whole spec: `:::openapi{spec path method}`,
+     * what GitBook's `{% openapi src path method %}` block shows. The tree is
+     * that operation's endpoint node alone; no such operation throws.
+     */
+    operation?: {
+        path: string;
+        method: string;
+    };
+}
+/**
+ * The operation a `:::openapi` directive selects from its props, or why it
+ * cannot: `path` and `method` come together or not at all.
+ */
+export declare function directiveOperation(props: Record<string, unknown> | undefined): {
+    operation?: {
+        path: string;
+        method: string;
+    };
+} | {
+    error: string;
+};
+export interface OpenApiEmbed {
+    /** Version line, description, then one section per tag of endpoint nodes. */
+    tree: TreeNode[];
+    /** One entry per tag section, for the page's table of contents. */
+    headings: Heading[];
+    operations: number;
+}
+/**
+ * A whole spec as the BODY of one page: what Swagger UI or Redoc show when a
+ * page embeds them. The info version and description, then a section per tag
+ * (declared order, then first use; untagged operations last, under "Other"),
+ * each holding its operations as `endpoint` nodes in document order.
+ *
+ * `spec` is a dereferenced spec (`prepareSpec`), and is not modified: the
+ * nodes are copies, so one parsed spec serves every page that embeds it.
+ *
+ * `specToPages` is the other shape — a page per operation — for a spec
+ * that IS the source. This one is for a spec a prose page points at.
+ */
+export declare function embedSpec(spec: any, options?: OpenApiEmbedOptions): OpenApiEmbed;