@publier/openapi 0.2.0 → 0.3.1

package/dist/index.d.mts

@@ -217,6 +217,16 @@ 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, 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;

package/dist/index.mjs

@@ -1 +1 @@
-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 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}))}}}function l(e){return s.sample(e)}function u(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?l(n.schema):void 0}function d(e){return JSON.stringify(e,null,2)}function f(e,t=`application/json`){let n=u(e,t);return n===void 0?void 0:d(n)}const p={curl:[`shell`,`curl`],javascript:[`javascript`,`fetch`],python:[`python`,`requests`],go:[`go`,`native`],java:[`java`,`nethttp`],csharp:[`csharp`,`httpclient`]};function m(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 h(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),d={path:{},query:{},header:{},cookie:{}};for(let[,e]of t.matchAll(/\{([^}]+)\}/g))e&&(d.path[e]=`{${e}}`);for(let e of l.getParameters()){let t=d[e.in];t&&e.in!==`path`&&(t[e.name]=`<value>`)}if(l.hasRequestBody()){let e=l.schema.requestBody,t=l.getContentType(),n=u(e?.content??{},t);l.isFormUrlEncoded()||l.isMultipart()?d.formData=n??{}:n!==void 0&&(d.body=n)}return a(c,l,d,m(c,l.getSecurity())).log.entries[0].request}function g(e){return e.replace(/%(?:25)?(3C|3E|7B|7D)/gi,(e,t)=>String.fromCharCode(Number.parseInt(t,16)))}function _(e,t){let[n,r]=p[t],a=new i(e).convert(n,r),o=Array.isArray(a)?a.find(e=>typeof e==`string`):a;return g(typeof o==`string`?o:``)}function v(e,t,n,r,i,a){return p[r]?_(h(e,t,n,i,a),r):``}const y=[`get`,`post`,`put`,`delete`,`patch`,`head`,`options`];function b(e,n={}){let{mergePathParameters:r=!1,includeWebhooks:i=!0}=n;return JSON.parse(t(JSON.stringify(e),r,i))}function x(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 S(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{y as HTTP_METHODS,c as asyncapiSource,x as buildNavigation,b as extractEndpoints,d as formatJson,v as generateCodeSample,l as generateExampleFromSchema,f as getMediaTypeExample,S 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

@@ -144,8 +144,12 @@ interface OpenApiCodeSample {
 /**
  * @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): Promise<OpenApiSpec>;
+export declare function parseOpenApiSpec(input: string | object, options?: {
+  onRead?: (file: string) => void;
+}): Promise<OpenApiSpec>;
 export {};

package/dist/parser.mjs

@@ -1 +1 @@
-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){let u=await e(l,{plugins:[i(),t(),r(),n()],treeShake:!1}),d=typeof u.swagger==`string`?s(u):u,f=await o(d);if(!f.valid){let e=f.errors.map(e=>e.message).join(`; `);throw Error(`Invalid OpenAPI spec: ${e}`)}let p=/* @__PURE__ */ new Map,{schema:m,errors:h}=a(d,{onDereference:({schema:e,ref:t})=>{p.set(e,t)}});if(h?.length)throw Error(`Invalid OpenAPI spec: ${h.map(e=>e.message).join(`; `)}`);return c(m,p,/* @__PURE__ */ new Set)}export{l 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{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){let t=await r(e,{plugins:[s(),i(),o(),a()],treeShake:!1}),n=typeof t.swagger==`string`?u(t):t,d=await l(n);if(!d.valid){let e=d.errors.map(e=>e.message).join(`; `);throw Error(`Invalid OpenAPI spec: ${e}`)}let f=/* @__PURE__ */ new Map,{schema:p,errors:h}=c(n,{onDereference:({schema:e,ref:t})=>{f.set(e,t)}});if(h?.length)throw Error(`Invalid OpenAPI spec: ${h.map(e=>e.message).join(`; `)}`);return m(p,f,/* @__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};
+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.2.0",
+  "version": "0.3.1",
   "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,7 +47,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@publier/native": "0.20.0",
+    "@publier/native": "0.22.0",
     "@readme/httpsnippet": "^11.4.1",
     "@readme/oas-to-har": "^39.0.1",
     "@scalar/json-magic": "^0.19.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/code-samples.astro

@@ -1,6 +1,6 @@
 ---
 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;
 

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';