@publier/openapi 0.1.19 → 0.3.0

package/dist/index.d.mts

@@ -216,7 +216,17 @@ interface AsyncApiSourceOptions {
  */
 export declare function asyncapiSource(options: AsyncApiSourceOptions): ContentSource;
 type SampleLang = 'curl' | 'javascript' | 'python' | 'go' | 'java' | 'csharp';
-export declare function generateCodeSample(method: HttpMethod, path: string, operation: OpenApiOperation, lang: SampleLang, baseUrl: string): string;
+export declare function generateCodeSample(method: HttpMethod, path: string, operation: OpenApiOperation, lang: SampleLang, baseUrl: string, spec?: OpenApiSpec): string;
+/**
+ * Build the full `(lang, label, code)` triple list the Rust renderer
+ * expects, in the canonical LANGUAGES order. Honors x-codeSamples
+ * overrides first, then falls back to auto-generation.
+ */
+export declare function buildCodeSamples(method: HttpMethod, path: string, operation: OpenApiOperation, baseUrl: string, spec?: OpenApiSpec): {
+  lang: SampleLang;
+  label: string;
+  code: string;
+}[];
 interface APIReferenceProps {
   method: HttpMethod;
   path: string;
@@ -244,6 +254,8 @@ interface CodeSamplesProps {
   method: HttpMethod;
   path: string;
   operation: OpenApiOperation;
+  /** The parsed specification; its security schemes put credentials into the samples. */
+  spec?: OpenApiSpec;
   baseUrl?: string;
 }
 interface RequestExampleProps {
@@ -321,8 +333,8 @@ interface ExtractEndpointsOptions {
 }
 export declare function extractEndpoints(spec: OpenApiSpec, options?: ExtractEndpointsOptions): EndpointEntry[];
 export declare function generateExampleFromSchema(schema: OpenApiSchema): unknown;
-export declare function getMediaTypeExample(content: Record<string, OpenApiMediaType>, mediaType?: string): string | undefined;
 export declare function formatJson(value: unknown): string;
+export declare function getMediaTypeExample(content: Record<string, OpenApiMediaType>, mediaType?: string): string | undefined;
 interface GenerateFilesOptions {
   /** The parsed OpenAPI spec. */
   spec: OpenApiSpec;

package/dist/index.mjs

@@ -1 +1 @@
-import{asyncapiSourceBuild as e,openapiDecodePlaceholders as t,openapiExtractEndpoints as n,openapiGetMediaTypeExample as r,openapiGetSnippetClient as i,openapiHarFromOperation as a,openapiNavigationBuild as o,openapiSourceBuild as s}from"@publier/native";import{HTTPSnippet as c}from"@readme/httpsnippet";import l from"openapi-sampler";function u(t){let{spec:n,baseUrl:r=``}=t,{pages:i,tree:a}=JSON.parse(e(JSON.stringify(n),r)),o=new Map(i.map(e=>[e.slug.join(`/`),e]));return{async getPage(e){return o.get(e.join(`/`))},async getPages(){return i},async getPageTree(){return a},async generateParams(){return i.map(e=>({slug:e.slug}))}}}function d(e,n,r,o,s){let l=i(o);if(!l)return``;let[u,d]=l,f=JSON.parse(a(e,n,JSON.stringify(r),s)),p=new c(f).convert(u,d),m=``;if(Array.isArray(p)){let e=p.find(e=>typeof e==`string`);typeof e==`string`&&(m=e)}else typeof p==`string`&&(m=p);return t(m)}const f=[`get`,`post`,`put`,`delete`,`patch`,`head`,`options`];function p(e,t={}){let{mergePathParameters:r=!1,includeWebhooks:i=!0}=t;return JSON.parse(n(JSON.stringify(e),r,i))}function m(e){return l.sample(e)}function h(e,t=`application/json`){let n=r(JSON.stringify(e),t);if(n===`__schema__`){let n=Object.keys(e)[0],r=e[t]??(n?e[n]:void 0);return r?.schema?g(m(r.schema)):void 0}return n??void 0}function g(e){return JSON.stringify(e,null,2)}function _(e,t={}){let{groupBy:n=`tag`,slugPrefix:r,excludeDeprecated:i=!1,includeWebhooks:a=!0}=t;return JSON.parse(o(JSON.stringify(e),n,r??null,i,a))}function v(e){let{spec:t,baseUrl:n=``}=e,{pages:r,tree:i}=JSON.parse(s(JSON.stringify(t),n)),a=new Map(r.map(e=>[e.slug.join(`/`),e]));return{async getPage(e){return a.get(e.join(`/`))},async getPages(){return r},async getPageTree(){return i},async generateParams(){return r.map(e=>({slug:e.slug}))}}}export{f as HTTP_METHODS,u as asyncapiSource,_ as buildNavigation,p as extractEndpoints,g as formatJson,d as generateCodeSample,m as generateExampleFromSchema,h as getMediaTypeExample,v as openapiSource};
+import{asyncapiSourceBuild as e,openapiExtractEndpoints as t,openapiNavigationBuild as n,openapiSourceBuild as r}from"@publier/native";import{HTTPSnippet as i}from"@readme/httpsnippet";import a from"@readme/oas-to-har";import o from"oas";import*as s from"openapi-sampler";function c(t){let{spec:n,baseUrl:r=``}=t,{pages:i,tree:a}=JSON.parse(e(JSON.stringify(n),r)),o=new Map(i.map(e=>[e.slug.join(`/`),e]));return{async getPage(e){return o.get(e.join(`/`))},async getPages(){return i},async getPageTree(){return a},async generateParams(){return i.map(e=>({slug:e.slug}))}}}const l=s.sample??s.default.sample;function u(e){return l(e)}function d(e,t=`application/json`){let n=e[t]??Object.values(e)[0];if(!n)return;if(n.example!==void 0)return n.example;let r=Object.values(n.examples??{}).find(e=>e.value!==void 0);return r?r.value:n.schema?u(n.schema):void 0}function f(e){return JSON.stringify(e,null,2)}function p(e,t=`application/json`){let n=d(e,t);return n===void 0?void 0:f(n)}const m=[`curl`,`javascript`,`python`,`go`,`java`,`csharp`],h={curl:`cURL`,javascript:`JavaScript`,python:`Python`,go:`Go`,java:`Java`,csharp:`C#`},g={curl:[`shell`,`curl`],javascript:[`javascript`,`fetch`],python:[`python`,`requests`],go:[`go`,`native`],java:[`java`,`nethttp`],csharp:[`csharp`,`httpclient`]},_={curl:`curl`,javascript:`javascript`,js:`javascript`,python:`python`,py:`python`,go:`go`,golang:`go`,java:`java`,csharp:`csharp`,"c#":`csharp`,cs:`csharp`};function v(e,t){let n=e.getDefinition().components?.securitySchemes??{},r={};for(let e of Object.keys(t[0]??{})){let t=n[e];t?.type===`http`&&t.scheme?.toLowerCase()===`basic`?r[e]={user:`<username>`,pass:`<password>`}:t?.type===`apiKey`?r[e]=`<api-key>`:t&&(r[e]=`<token>`)}return r}function y(e,t,n,r,i){let s={openapi:`3.0.0`,info:{title:`API`,version:`1`},...i,servers:[{url:r}],paths:{...i?.paths,[t]:{...i?.paths?.[t],[e]:n}}},c=new o(s),l=c.operation(t,e),u={path:{},query:{},header:{},cookie:{}};for(let[,e]of t.matchAll(/\{([^}]+)\}/g))e&&(u.path[e]=`{${e}}`);for(let e of l.getParameters()){let t=u[e.in];t&&e.in!==`path`&&(t[e.name]=`<value>`)}if(l.hasRequestBody()){let e=l.schema.requestBody,t=l.getContentType(),n=d(e?.content??{},t);l.isFormUrlEncoded()||l.isMultipart()?u.formData=n??{}:n!==void 0&&(u.body=n)}return a(c,l,u,v(c,l.getSecurity())).log.entries[0].request}function b(e){return e.replace(/%(?:25)?(3C|3E|7B|7D)/gi,(e,t)=>String.fromCharCode(Number.parseInt(t,16)))}function x(e,t){let[n,r]=g[t],a=new i(e).convert(n,r),o=Array.isArray(a)?a.find(e=>typeof e==`string`):a;return b(typeof o==`string`?o:``)}function S(e,t,n,r,i,a){return g[r]?x(y(e,t,n,i,a),r):``}function C(e){let t=/* @__PURE__ */ new Map;for(let{lang:n,source:r}of e){let e=_[n.trim().toLowerCase()];e&&t.set(e,r)}return t}function w(e,t,n,r,i){let a=C(n[`x-codeSamples`]??[]),o=m.some(e=>!a.has(e))?y(e,t,n,r,i):void 0;return m.map(e=>({lang:e,label:h[e],code:a.get(e)??(o?x(o,e):``)}))}const T=[`get`,`post`,`put`,`delete`,`patch`,`head`,`options`];function E(e,n={}){let{mergePathParameters:r=!1,includeWebhooks:i=!0}=n;return JSON.parse(t(JSON.stringify(e),r,i))}function D(e,t={}){let{groupBy:r=`tag`,slugPrefix:i,excludeDeprecated:a=!1,includeWebhooks:o=!0}=t;return JSON.parse(n(JSON.stringify(e),r,i??null,a,o))}function O(e){let{spec:t,baseUrl:n=``}=e,{pages:i,tree:a}=JSON.parse(r(JSON.stringify(t),n)),o=new Map(i.map(e=>[e.slug.join(`/`),e]));return{async getPage(e){return o.get(e.join(`/`))},async getPages(){return i},async getPageTree(){return a},async generateParams(){return i.map(e=>({slug:e.slug}))}}}export{T as HTTP_METHODS,c as asyncapiSource,w as buildCodeSamples,D as buildNavigation,E as extractEndpoints,f as formatJson,S as generateCodeSample,u as generateExampleFromSchema,p as getMediaTypeExample,O as openapiSource};

package/dist/parser.d.mts

@@ -1,3 +1,15 @@
+/**
+ * OpenAPI ingestion on @scalar/openapi-parser: load (file, URL or text; JSON or
+ * YAML; external `$ref`s), Swagger 2 → 3.0 upgrade, validation, dereference.
+ *
+ * The Rust renderers read a fully inlined document as JSON, so the result is
+ * made JSON-safe: a `$ref` that points back into the node being expanded is
+ * left as `{ "$ref": "#/…" }` (the shape the renderers already treat as
+ * "stop here"), instead of a cyclic object graph.
+ *
+ * 3.0 documents stay 3.0 on purpose: the 3.0 → 3.1 upgrade rewrites `nullable`
+ * into `type: [..., "null"]`, which the schema renderers cannot read.
+ */
 interface OpenApiSpec {
   openapi: string;
   info: OpenApiInfo;
@@ -129,5 +141,15 @@ interface OpenApiCodeSample {
   label?: string;
   source: string;
 }
-export declare function parseOpenApiSpec(input: string): OpenApiSpec;
+/**
+ * @param input File path, URL, or the JSON/YAML text of a spec, or a parsed
+ * spec object. Relative external `$ref`s resolve against a path or URL input.
+ * @param options.onRead Called with each local file the parser reads (the spec
+ * and the files it `$ref`s), so a dev server can watch them.
+ * @throws with the parser's validation messages when the document is not a
+ * valid OpenAPI/Swagger document.
+ */
+export declare function parseOpenApiSpec(input: string | object, options?: {
+  onRead?: (file: string) => void;
+}): Promise<OpenApiSpec>;
 export {};

package/dist/parser.mjs

@@ -1 +1 @@
-import{openapiParseOpenapiSpec as e}from"@publier/native";import{parse as t}from"yaml";function n(n){let r;try{JSON.parse(n),r=n}catch{r=JSON.stringify(t(n))}return JSON.parse(e(r))}export{n as parseOpenApiSpec};
+import{bundle as e}from"@scalar/json-magic/bundle";import{fetchUrls as t,parseJson as n,parseYaml as r}from"@scalar/json-magic/bundle/plugins/browser";import{readFiles as i}from"@scalar/json-magic/bundle/plugins/node";import{dereference as a,validate as o}from"@scalar/openapi-parser";import{upgradeFromTwoToThree as s}from"@scalar/openapi-upgrader/2.0-to-3.0";function c(e,t,n){if(typeof e!=`object`||!e)return e;let r=t.get(e);if(r!==void 0){if(n.has(r))return{$ref:r};n.add(r)}let i=Array.isArray(e)?e.map(e=>c(e,t,n)):Object.fromEntries(Object.entries(e).map(([e,r])=>[e,c(r,t,n)]));return r!==void 0&&n.delete(r),i}async function l(l,u={}){let d=i(),f={...d,exec:e=>(u.onRead?.(e),d.exec(e))},p=await e(l,{plugins:[f,t(),r(),n()],treeShake:!1}),m=typeof p.swagger==`string`?s(p):p,h=await o(m);if(!h.valid){let e=h.errors.map(e=>e.message).join(`; `);throw Error(`Invalid OpenAPI spec: ${e}`)}let g=/* @__PURE__ */ new Map,{schema:_,errors:v}=a(m,{onDereference:({schema:e,ref:t})=>{g.set(e,t)}});if(v?.length)throw Error(`Invalid OpenAPI spec: ${v.map(e=>e.message).join(`; `)}`);return c(_,g,/* @__PURE__ */ new Set)}export{l as parseOpenApiSpec};

package/dist/server.mjs

@@ -1 +1 @@
-import{readFileSync as e}from"node:fs";import{openapiExtractEndpoints as t,openapiMergeSpecs as n,openapiNavigationBuild as r,openapiParseOpenapiSpec as i}from"@publier/native";import{parse as a}from"yaml";const o=[`get`,`post`,`put`,`delete`,`patch`,`head`,`options`];function s(e,n={}){let{mergePathParameters:r=!1,includeWebhooks:i=!0}=n;return JSON.parse(t(JSON.stringify(e),r,i))}function c(e,t={}){let{groupBy:n=`tag`,slugPrefix:i,excludeDeprecated:a=!1,includeWebhooks:o=!0}=t;return JSON.parse(r(JSON.stringify(e),n,i??null,a,o))}function l(e){let t;try{JSON.parse(e),t=e}catch{t=JSON.stringify(a(e))}return JSON.parse(i(t))}function u(t){let r=null;async function i(){if(r&&!t.disableCache)return r;let i=[];for(let n of t.input)if(typeof n==`string`){let t;if(n.startsWith(`http:`)||n.startsWith(`https:`)){let e=await fetch(n);if(!e.ok)throw Error(`Failed to fetch OpenAPI spec from "${n}": ${e.status} ${e.statusText}`);t=await e.text()}else t=e(n,`utf-8`);i.push(l(t))}else i.push(n);if(i.length===0)throw Error(`No OpenAPI specs provided`);return i.length===1?(r=i[0],r):(r=JSON.parse(n(JSON.stringify(i))),r)}return{getSpec:i,async getOperation(e){let t=await i();for(let[n,r]of Object.entries(t.paths))for(let t of o){let i=r[t];if(i?.operationId===e)return{method:t,path:n,operation:i}}},async getOperationByPath(e,t){let n=(await i()).paths[e]?.[t];return n?{method:t,path:e,operation:n}:void 0},async getOperationsByTag(e){return s(await i(),{mergePathParameters:!0}).filter(t=>t.operation.tags?.includes(e)).map(({method:e,path:t,operation:n})=>({method:e,path:t,operation:n}))},async getEndpoints(){return s(await i(),{mergePathParameters:!0})},async getNavigation(e){return c(await i(),e)}}}export{u as createOpenAPI};
+import{openapiExtractEndpoints as e,openapiMergeSpecs as t,openapiNavigationBuild as n}from"@publier/native";import{bundle as r}from"@scalar/json-magic/bundle";import{fetchUrls as i,parseJson as a,parseYaml as o}from"@scalar/json-magic/bundle/plugins/browser";import{readFiles as s}from"@scalar/json-magic/bundle/plugins/node";import{dereference as c,validate as l}from"@scalar/openapi-parser";import{upgradeFromTwoToThree as u}from"@scalar/openapi-upgrader/2.0-to-3.0";const d=[`get`,`post`,`put`,`delete`,`patch`,`head`,`options`];function f(t,n={}){let{mergePathParameters:r=!1,includeWebhooks:i=!0}=n;return JSON.parse(e(JSON.stringify(t),r,i))}function p(e,t={}){let{groupBy:r=`tag`,slugPrefix:i,excludeDeprecated:a=!1,includeWebhooks:o=!0}=t;return JSON.parse(n(JSON.stringify(e),r,i??null,a,o))}function m(e,t,n){if(typeof e!=`object`||!e)return e;let r=t.get(e);if(r!==void 0){if(n.has(r))return{$ref:r};n.add(r)}let i=Array.isArray(e)?e.map(e=>m(e,t,n)):Object.fromEntries(Object.entries(e).map(([e,r])=>[e,m(r,t,n)]));return r!==void 0&&n.delete(r),i}async function h(e,t={}){let n=s(),d={...n,exec:e=>(t.onRead?.(e),n.exec(e))},f=await r(e,{plugins:[d,i(),o(),a()],treeShake:!1}),p=typeof f.swagger==`string`?u(f):f,h=await l(p);if(!h.valid){let e=h.errors.map(e=>e.message).join(`; `);throw Error(`Invalid OpenAPI spec: ${e}`)}let g=/* @__PURE__ */ new Map,{schema:_,errors:v}=c(p,{onDereference:({schema:e,ref:t})=>{g.set(e,t)}});if(v?.length)throw Error(`Invalid OpenAPI spec: ${v.map(e=>e.message).join(`; `)}`);return m(_,g,/* @__PURE__ */ new Set)}function g(e){let n=null;async function r(){if(n&&!e.disableCache)return n;let r=[];for(let t of e.input)typeof t==`string`?r.push(await h(t)):r.push(t);if(r.length===0)throw Error(`No OpenAPI specs provided`);return r.length===1?(n=r[0],n):(n=JSON.parse(t(JSON.stringify(r))),n)}return{getSpec:r,async getOperation(e){let t=await r();for(let[n,r]of Object.entries(t.paths))for(let t of d){let i=r[t];if(i?.operationId===e)return{method:t,path:n,operation:i}}},async getOperationByPath(e,t){let n=(await r()).paths[e]?.[t];return n?{method:t,path:e,operation:n}:void 0},async getOperationsByTag(e){return f(await r(),{mergePathParameters:!0}).filter(t=>t.operation.tags?.includes(e)).map(({method:e,path:t,operation:n})=>({method:e,path:t,operation:n}))},async getEndpoints(){return f(await r(),{mergePathParameters:!0})},async getNavigation(e){return p(await r(),e)}}}export{g as createOpenAPI};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@publier/openapi",
-  "version": "0.1.19",
+  "version": "0.3.0",
   "license": "UNLICENSED",
   "type": "module",
   "files": [
@@ -8,6 +8,8 @@
     "src/components/**/*.astro",
     "src/components/**/*.ts",
     "src/components/props.ts",
+    "src/types.ts",
+    "src/async-types.ts",
     "!src/**/__tests__/**",
     "!src/**/*.test.ts"
   ],
@@ -45,8 +47,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@publier/native": "0.19.0",
+    "@publier/native": "0.21.0",
     "@readme/httpsnippet": "^11.4.1",
+    "@readme/oas-to-har": "^39.0.1",
+    "@scalar/json-magic": "^0.19.1",
+    "@scalar/openapi-parser": "^0.29.22",
+    "@scalar/openapi-upgrader": "^0.4.9",
+    "oas": "^39.0.1",
     "openapi-sampler": "^1.7.10",
     "yaml": "^2.9.1"
   },

package/src/async-types.ts

@@ -0,0 +1,59 @@
+import type { OpenApiSchema } from './types.ts';
+
+export interface AsyncApiSpec {
+	asyncapi: string; 
+	info: { title: string; description?: string; version: string };
+	servers?: Record<string, AsyncApiServer>;
+	channels?: Record<string, AsyncApiChannel>;
+	operations?: Record<string, AsyncApiOperation>;
+	components?: AsyncApiComponents;
+}
+
+export interface AsyncApiServer {
+	host: string;
+	protocol: string; 
+	pathname?: string;
+	description?: string;
+	tags?: { name: string; description?: string }[];
+}
+
+export interface AsyncApiChannel {
+	address?: string;
+	description?: string;
+	messages?: Record<string, AsyncApiMessage | { $ref: string }>;
+	parameters?: Record<string, AsyncApiParameter>;
+	tags?: { name: string; description?: string }[];
+}
+
+export interface AsyncApiOperation {
+	action: 'send' | 'receive';
+	channel: { $ref: string };
+	summary?: string;
+	description?: string;
+	messages?: ({ $ref: string } | AsyncApiMessage)[];
+	tags?: { name: string; description?: string }[];
+}
+
+export interface AsyncApiMessage {
+	name?: string;
+	title?: string;
+	summary?: string;
+	description?: string;
+	contentType?: string;
+	payload?: OpenApiSchema;
+	headers?: OpenApiSchema;
+	tags?: { name: string; description?: string }[];
+}
+
+export interface AsyncApiParameter {
+	description?: string;
+	default?: string;
+	enum?: string[];
+}
+
+export interface AsyncApiComponents {
+	schemas?: Record<string, OpenApiSchema>;
+	messages?: Record<string, AsyncApiMessage>;
+	channels?: Record<string, AsyncApiChannel>;
+	operations?: Record<string, AsyncApiOperation>;
+}

package/src/components/api-reference.astro

@@ -16,6 +16,6 @@ const L = JSON.parse(openapiRenderApiReferenceShell());
 <APIPage method={method} path={path} operation={operation} />
 <Fragment set:html={L.mainCloseAsideOpen} />
 <RequestExample method={method} path={path} operation={operation} baseUrl={baseUrl} />
-<CodeSamples method={method} path={path} operation={operation} baseUrl={baseUrl} />
+<CodeSamples method={method} path={path} operation={operation} spec={spec} baseUrl={baseUrl} />
 <ResponseExample responses={operation.responses} instanceId={instanceId} />
 <Fragment set:html={L.close} />

package/src/components/code-samples.astro

@@ -1,11 +1,11 @@
 ---
 import { openapiRenderCodeSamples } from '@publier/native';
-import { buildCodeSamples } from '../code-sample-generators.ts';
+import { buildCodeSamples } from '@publier/openapi';
 import type { CodeSamplesProps } from './props.ts';
 type Props = CodeSamplesProps;
 
-const { method, path, operation, baseUrl = 'https://api.example.com' } = Astro.props;
-const samples = buildCodeSamples(method, path, operation, baseUrl);
+const { method, path, operation, spec, baseUrl = 'https://api.example.com' } = Astro.props;
+const samples = buildCodeSamples(method, path, operation, baseUrl, spec);
 const html = openapiRenderCodeSamples(method, path, JSON.stringify(samples));
 ---
 

package/src/components/props.ts

@@ -43,6 +43,8 @@ export interface CodeSamplesProps {
 	method: HttpMethod;
 	path: string;
 	operation: OpenApiOperation;
+	
+	spec?: OpenApiSpec;
 	baseUrl?: string;
 }
 

package/src/components/request-example.astro

@@ -1,6 +1,6 @@
 ---
 import { openapiRenderRequestExample } from '@publier/native';
-import { getMediaTypeExample } from '../example-utils.ts';
+import { getMediaTypeExample } from '@publier/openapi';
 import type { RequestExampleProps } from './props.ts';
 type Props = RequestExampleProps;
 

package/src/components/response-example.astro

@@ -1,6 +1,6 @@
 ---
 import { openapiRenderResponseExample } from '@publier/native';
-import { getMediaTypeExample } from '../example-utils.ts';
+import { getMediaTypeExample } from '@publier/openapi';
 import type { ResponseExampleProps } from './props.ts';
 type Props = ResponseExampleProps;
 

package/src/types.ts

@@ -0,0 +1,140 @@
+export interface OpenApiSpec {
+	openapi: string;
+	info: OpenApiInfo;
+	servers?: OpenApiServer[];
+	paths: Record<string, OpenApiPathItem>;
+	/**
+	 * OpenAPI 3.1 webhooks — server-to-client push endpoints, keyed by name.
+	 * Shape-identical to path items but not part of the HTTP routing table.
+	 */
+	webhooks?: Record<string, OpenApiPathItem>;
+	components?: OpenApiComponents;
+	security?: Record<string, string[]>[];
+	tags?: OpenApiTag[];
+}
+
+export interface OpenApiInfo {
+	title: string;
+	description?: string;
+	version: string;
+}
+
+export interface OpenApiServer {
+	url: string;
+	description?: string;
+}
+
+export interface OpenApiPathItem {
+	get?: OpenApiOperation;
+	post?: OpenApiOperation;
+	put?: OpenApiOperation;
+	delete?: OpenApiOperation;
+	patch?: OpenApiOperation;
+	head?: OpenApiOperation;
+	options?: OpenApiOperation;
+	summary?: string;
+	description?: string;
+	parameters?: OpenApiParameter[];
+}
+
+export interface OpenApiOperation {
+	operationId?: string;
+	summary?: string;
+	description?: string;
+	tags?: string[];
+	parameters?: OpenApiParameter[];
+	requestBody?: OpenApiRequestBody;
+	responses: Record<string, OpenApiResponse>;
+	/**
+	 * OpenAPI 3.0+ callbacks — out-of-band requests the service will make in
+	 * response to this operation.
+	 */
+	callbacks?: Record<string, Record<string, OpenApiPathItem>>;
+	security?: Record<string, string[]>[];
+	deprecated?: boolean;
+	'x-codeSamples'?: OpenApiCodeSample[];
+}
+
+export interface OpenApiParameter {
+	name: string;
+	in: 'path' | 'query' | 'header' | 'cookie';
+	description?: string;
+	required?: boolean;
+	schema?: OpenApiSchema;
+	deprecated?: boolean;
+}
+
+export interface OpenApiRequestBody {
+	description?: string;
+	required?: boolean;
+	content: Record<string, OpenApiMediaType>;
+}
+
+export interface OpenApiResponse {
+	description: string;
+	content?: Record<string, OpenApiMediaType>;
+	headers?: Record<string, { description?: string; schema?: OpenApiSchema }>;
+}
+
+export interface OpenApiMediaType {
+	schema?: OpenApiSchema;
+	example?: unknown;
+	examples?: Record<string, { value: unknown; summary?: string }>;
+}
+
+export interface OpenApiSchema {
+	type?: string;
+	format?: string;
+	description?: string;
+	properties?: Record<string, OpenApiSchema>;
+	items?: OpenApiSchema;
+	required?: string[];
+	enum?: unknown[];
+	default?: unknown;
+	oneOf?: OpenApiSchema[];
+	anyOf?: OpenApiSchema[];
+	allOf?: OpenApiSchema[];
+	$ref?: string;
+	nullable?: boolean;
+	readOnly?: boolean;
+	writeOnly?: boolean;
+	deprecated?: boolean;
+	example?: unknown;
+	title?: string;
+	minimum?: number;
+	maximum?: number;
+	pattern?: string;
+	minLength?: number;
+	maxLength?: number;
+	additionalProperties?: boolean | OpenApiSchema;
+}
+
+export interface OpenApiComponents {
+	schemas?: Record<string, OpenApiSchema>;
+	parameters?: Record<string, OpenApiParameter>;
+	responses?: Record<string, OpenApiResponse>;
+	requestBodies?: Record<string, OpenApiRequestBody>;
+	securitySchemes?: Record<string, OpenApiSecurityScheme>;
+}
+
+export interface OpenApiSecurityScheme {
+	type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+	description?: string;
+	name?: string;
+	in?: 'query' | 'header' | 'cookie';
+	scheme?: string;
+	bearerFormat?: string;
+}
+
+export interface OpenApiTag {
+	name: string;
+	description?: string;
+}
+
+export interface OpenApiCodeSample {
+	lang: string;
+	label?: string;
+	source: string;
+}
+
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head' | 'options';