@dogsbay/format-openapi 0.2.0-beta.12 → 0.2.0-beta.121

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,gBAAgB,CAAC;AAGxE,eAAO,MAAM,MAAM,EAAE,YAiBpB,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,gBAAgB,CAAC;AAGxE,eAAO,MAAM,MAAM,EAAE,YAoBpB,CAAC"}

package/dist/cli.js

@@ -10,6 +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,
         });
     },
 };

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnE,MAAM,CAAC,MAAM,MAAM,GAAiB;IAClC,IAAI,EAAE,SAAS;IACf,SAAS,EAAE,IAAI;IACf,SAAS,EAAE,KAAK;IAChB,YAAY,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC;IACzD,aAAa,EAAE,EAAE;IACjB,aAAa,EAAE,EAAE;IAEjB,KAAK,CAAC,MAAM,CACV,MAAc,EACd,IAA6B;QAE7B,OAAO,gBAAgB,CAAC,MAAM,EAAE;YAC9B,UAAU,EAAE,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;YAC7E,OAAO,EAAE,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;SACrE,CAAC,CAAC;IACL,CAAC;CACF,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnE,MAAM,CAAC,MAAM,MAAM,GAAiB;IAClC,IAAI,EAAE,SAAS;IACf,SAAS,EAAE,IAAI;IACf,SAAS,EAAE,KAAK;IAChB,YAAY,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC;IACzD,aAAa,EAAE,EAAE;IACjB,aAAa,EAAE,EAAE;IAEjB,KAAK,CAAC,MAAM,CACV,MAAc,EACd,IAA6B;QAE7B,OAAO,gBAAgB,CAAC,MAAM,EAAE;YAC9B,UAAU,EAAE,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;YAC7E,OAAO,EAAE,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;YACpE,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC;gBAC9C,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;gBACtE,CAAC,CAAC,SAAS;SACd,CAAC,CAAC;IACL,CAAC;CACF,CAAC"}

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) {

package/dist/code-samples.js.map

@@ -1 +1 @@
-{"version":3,"file":"code-samples.js","sourceRoot":"","sources":["../src/code-samples.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,MAAM,UAAU,kBAAkB,CAChC,SAAc,EACd,MAAc,EACd,IAAY,EACZ,OAAe;IAEf,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC5C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC;IACrC,OAAO,mBAAmB,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,iBAAiB,CAAC,SAAc;IACvC,MAAM,GAAG,GACP,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,IAAI,SAAS,CAAC,gBAAgB,CAAC,CAAC,CAAC;QAC1E,EAAE,CAAC;IACL,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QACxB,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,SAAS;QAClD,MAAM,QAAQ,GACZ,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI;YAC1C,CAAC,CAAC,KAAK,CAAC,IAAI;YACZ,CAAC,CAAC,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,KAAK,CAAC,QAAQ;gBACpD,CAAC,CAAC,KAAK,CAAC,QAAQ;gBAChB,CAAC,CAAC,SAAS,CAAC;QAClB,MAAM,IAAI,GAAG,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;QACzE,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI;YAAE,SAAS;QACjC,MAAM,MAAM,GAAe,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAC9C,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK;YAAE,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC/E,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,mBAAmB,CAC1B,MAAc,EACd,IAAY,EACZ,OAAe;IAEf,MAAM,GAAG,GAAG,GAAG,OAAO,GAAG,IAAI,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IAEnC,OAAO;QACL;YACE,QAAQ,EAAE,MAAM;YAChB,IAAI,EACF,KAAK,KAAK,KAAK;gBACb,CAAC,CAAC,SAAS,GAAG,uCAAuC;gBACrD,CAAC,CAAC,WAAW,KAAK,KAAK,GAAG,iFAAiF;SAChH;QACD;YACE,QAAQ,EAAE,QAAQ;YAClB,IAAI,EACF,KAAK,KAAK,KAAK;gBACb,CAAC,CAAC,+CAA+C,GAAG,4BAA4B;gBAChF,CAAC,CAAC,0CAA0C,MAAM,WAAW,GAAG,4CAA4C;SACjH;QACD;YACE,QAAQ,EAAE,YAAY;YACtB,IAAI,EACF,KAAK,KAAK,KAAK;gBACb,CAAC,CAAC,iCAAiC,GAAG,0CAA0C;gBAChF,CAAC,CAAC,iCAAiC,GAAG,oBAAoB,KAAK,+HAA+H;SACnM;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"code-samples.js","sourceRoot":"","sources":["../src/code-samples.ts"],"names":[],"mappings":"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"}

package/dist/core.d.ts

@@ -0,0 +1,112 @@
+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;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAK7E,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAY3E,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,GAAG,EACT,OAAO,GAAE,mBAAwB,GAChC;IAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,GAAG,EAAE,OAAO,EAAE,CAAA;CAAE,CAuDzC;AA4RD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAO1F;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,SAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAuBnF;AA2ID;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,EAChD,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GACpC;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAiB5D;AA4BD,+CAA+C;AAC/C,eAAO,MAAM,eAAe,2BAA2B,CAAC;AAmHxD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAiB5C;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3B;;;;OAIG;IACH,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG;IAAE,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAOnJ;AAED,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,mEAAmE;IACnE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAoDpF"}