Documents and operations

Use these types to author an OpenAPI document or describe input to the generator. They describe data; they do not fetch a document, enforce the OpenAPI specification, or execute an operation.

Document contract

Type	Required fields and behavior
OpenAPI	openapi: string, info: Info, paths: Paths; optional servers, components, security, tags and externalDocs
Info	All fields optional in this package, including title/version; this is less strict than a specification validator
Contact, License	Contact fields optional; License requires name
Server, ServerVariable	Server requires url; variable requires default; no URL interpolation happens here
Tag, ExternalDocumentation	Require name and url respectively; metadata only
Paths, PathItem, HTTPMethod	Paths maps strings to items; eight lowercase method keys, shared parameters/servers, optional $ref
Operation	Requires responses; optional operationId, tags, parameters, body, callbacks, security and servers

Parameters and responses

Parameter requires name and in (query, header, path, cookie). All serialization hints (style, explode, allowReserved, allowEmptyValue) are optional; the package supplies no runtime defaults. It does not enforce path-parameter required: true, or mutual exclusion of schema/content and example/examples.

RequestBody requires a media-type-to-MediaType content map. MediaType can contain a Schema/Reference, examples, and per-property Encoding. Header has parameter-like fields without name/in. Responses maps string status keys to Response | Reference | undefined, with optional default. A Response's description is optional in these declarations. Link describes another operation by ID/ref; Callback maps runtime-expression strings to PathItem. None follows links, sends callbacks, negotiates content, or validates response status.

Complete document

The following is a compile-time example with no network or resources to release. Type checking catches misspelled declared fields and incompatible values; external JSON still needs application-level validation.

import type { OpenAPI } from '@ahoo-wang/fetcher-openapi';

const document: OpenAPI = {
  openapi: '3.0.3',
  info: { title: 'Items', version: '1.0.0' },
  tags: [{ name: 'Items' }],
  paths: {
    '/items/{id}': {
      get: {
        operationId: 'getItem',
        tags: ['Items'],
        parameters: [
          {
            name: 'id',
            in: 'path',
            required: true,
            schema: { type: 'string' },
          },
        ],
        responses: {
          '200': {
            description: 'Found',
            content: {
              'application/json': {
                schema: {
                  type: 'object',
                  required: ['id'],
                  properties: { id: { type: 'string' } },
                },
              },
            },
          },
        },
      },
    },
  },
};
console.log(document.paths['/items/{id}'].get?.operationId);

OpenAPI

packages/openapi/src/openAPI.ts:41

export interface OpenAPI extends Extensible {
  openapi: string;
  info: Info;
  servers?: Server[];
  paths: Paths;
  components?: Components;
  security?: SecurityRequirement[];
  tags?: Tag[];
  externalDocs?: ExternalDocumentation;
}

Contact

packages/openapi/src/info.ts:27

export interface Contact extends Extensible {
  name?: string;
  url?: string;
  email?: string;
}

License

packages/openapi/src/info.ts:39

export interface License extends Extensible {
  name: string;
  url?: string;
}

Info

packages/openapi/src/info.ts:54

export interface Info extends Extensible {
  title?: string;
  description?: string;
  termsOfService?: string;
  contact?: Contact;
  license?: License;
  version?: string;
}

ServerVariable

packages/openapi/src/server.ts:27

export interface ServerVariable extends Extensible {
  enum?: string[];
  default: string;
  description?: string;
}

Server

packages/openapi/src/server.ts:40

export interface Server extends Extensible {
  url: string;
  description?: string;
  variables?: Record<string, ServerVariable>;
}

Operation

packages/openapi/src/paths.ts:44

export interface Operation extends Extensible {
  tags?: string[];
  summary?: string;
  description?: string;
  externalDocs?: ExternalDocumentation;
  operationId?: string;
  parameters?: (Parameter | Reference)[];
  requestBody?: RequestBody | Reference;
  responses: Responses;
  callbacks?: Record<string, Callback | Reference>;
  deprecated?: boolean;
  security?: SecurityRequirement[];
  servers?: Server[];
}

PathItem

packages/openapi/src/paths.ts:76

export interface PathItem extends Extensible {
  $ref?: string;
  summary?: string;
  description?: string;
  get?: Operation;
  put?: Operation;
  post?: Operation;
  delete?: Operation;
  options?: Operation;
  head?: Operation;
  patch?: Operation;
  trace?: Operation;
  servers?: Server[];
  parameters?: (Parameter | Reference)[];
}

Paths

packages/openapi/src/paths.ts:95

export interface Paths extends Extensible {
  [path: string]: PathItem;
}

Parameter

packages/openapi/src/parameters.ts:40

export interface Parameter extends Extensible {
  name: string;
  in: ParameterLocation;
  description?: string;
  required?: boolean;
  deprecated?: boolean;
  allowEmptyValue?: boolean;
  style?: string;
  explode?: boolean;
  allowReserved?: boolean;
  schema?: Schema | Reference;
  example?: any;
  examples?: Record<string, Example | Reference>;
  content?: Record<string, MediaType>;
}

RequestBody

packages/openapi/src/parameters.ts:63

export interface RequestBody extends Extensible {
  description?: string;
  content: Record<string, MediaType>;
  required?: boolean;
}

MediaType

packages/openapi/src/parameters.ts:77

export interface MediaType extends Extensible {
  schema?: Schema | Reference;
  example?: any;
  examples?: Record<string, Example | Reference>;
  encoding?: Record<string, Encoding>;
}

Encoding

packages/openapi/src/parameters.ts:93

export interface Encoding extends Extensible {
  contentType?: string;
  headers?: Record<string, Header | Reference>;
  style?: string;
  explode?: boolean;
  allowReserved?: boolean;
}

Link

packages/openapi/src/responses.ts:35

export interface Link extends Extensible {
  operationRef?: string;
  operationId?: string;
  parameters?: Record<string, any>;
  requestBody?: any;
  description?: string;
  server?: Server;
}

Response

packages/openapi/src/responses.ts:52

export interface Response extends Extensible {
  description?: string;
  headers?: Record<string, Header | Reference>;
  content?: Record<string, MediaType>;
  links?: Record<string, Link | Reference>;
}

Responses

packages/openapi/src/responses.ts:62

export interface Responses extends Extensible {
  default?: Response | Reference;

  [httpCode: string]: Response | Reference | undefined;
}

Callback

packages/openapi/src/responses.ts:71

export interface Callback extends Extensible {
  [expression: string]: PathItem;
}

Tag

packages/openapi/src/tags.ts:24

export interface Tag extends Extensible {
  name: string;
  description?: string;
  externalDocs?: ExternalDocumentation;
}

HTTPMethod

packages/openapi/src/base-types.ts:26

export type HTTPMethod =
  'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace';

ParameterLocation

packages/openapi/src/base-types.ts:39

export type ParameterLocation = 'query' | 'header' | 'path' | 'cookie';

ExternalDocumentation

packages/openapi/src/base-types.ts:59

export interface ExternalDocumentation extends Extensible {
  description?: string;
  url: string;
}

Example

packages/openapi/src/base-types.ts:72

export interface Example extends Extensible {
  summary?: string;
  description?: string;
  value?: any;
  externalValue?: string;
}

Header

packages/openapi/src/base-types.ts:82

export interface Header extends Extensible {
  description?: string;
  required?: boolean;
  deprecated?: boolean;
  allowEmptyValue?: boolean;
  style?: string;
  explode?: boolean;
  allowReserved?: boolean;
  schema?: Schema | Reference;
  example?: any;
  examples?: Record<string, Example | Reference>;
  content?: Record<string, MediaType>;
}