npm install @api-platform/api-doc-parser

Using Pnpm:

pnpm add @api-platform/api-doc-parser

With Yarn:

yarn add @api-platform/api-doc-parser

Using Bun:

bun add @api-platform/api-doc-parser

🚀 Usage

Hydra

import { parseHydraDocumentation } from "@api-platform/api-doc-parser";

const { api, response, status } = await parseHydraDocumentation(
  "https://demo.api-platform.com",
);

OpenAPI v2 (formerly known as Swagger)

import { parseSwaggerDocumentation } from "@api-platform/api-doc-parser";

const { api, response, status } = await parseSwaggerDocumentation(
  "https://demo.api-platform.com/docs.json",
);

OpenAPI v3

import { parseOpenApi3Documentation } from "@api-platform/api-doc-parser";

const { api, response, status } = await parseOpenApi3Documentation(
  "https://demo.api-platform.com/docs.jsonopenapi?spec_version=3.0.0",
);

GraphQL

import { parseGraphQl } from "@api-platform/api-doc-parser";

const { api, response } = await parseGraphQl(
  "https://demo.api-platform.com/graphql",
);

Type definitions

Each parse function returns a Promise that resolves to an object containing the normalized API structure, the raw documentation, and the HTTP status code:

OpenAPI 3

function parseOpenApi3Documentation(
  entrypointUrl: string,
  options?: RequestInitExtended,
): Promise<{
  api: Api;
  response: OpenAPIV3.Document;
  status: number;
}>;

Swagger

function parseSwaggerDocumentation(entrypointUrl: string): Promise<{
  api: Api;
  response: OpenAPIV2.Document;
  status: number;
}>;

Hydra

function parseHydraDocumentation(
  entrypointUrl: string,
  options?: RequestInitExtended,
): Promise<{
  api: Api;
  response: Response;
  status: number;
}>;

GraphQL

function parseGraphQl(
  entrypointUrl: string,
  options?: RequestInit,
): Promise<{
  api: Api;
  response: Response;
}>;

Api

Represents the root of the parsed API, containing the entrypoint URL, an optional title, and a list of resources.

interface Api {
  entrypoint: string;
  title?: string;
  resources?: Resource[];
}

Resource

Describes an API resource (such as an entity or collection), including its fields, operations, and metadata.

interface Resource {
  name: string | null;
  url: string | null;
  id?: string | null;
  title?: string | null;
  description?: string | null;
  deprecated?: boolean | null;
  fields?: Field[] | null;
  readableFields?: Field[] | null;
  writableFields?: Field[] | null;
  parameters?: Parameter[] | null;
  getParameters?: () => Promise<Parameter[]> | null;
  operations?: Operation[] | null;
}

Field

Represents a property of a resource, including its type, constraints, and metadata.

interface Field {
  name: string | null;
  id?: string | null;
  range?: string | null;
  type?: FieldType | null;
  arrayType?: FieldType | null;
  enum?: { [key: string | number]: string | number } | null;
  reference?: string | Resource | null;
  embedded?: Resource | null;
  required?: boolean | null;
  nullable?: boolean | null;
  description?: string | null;
  maxCardinality?: number | null;
  deprecated?: boolean | null;
}

Parameter

Represents a query parameter for a collection/list operation, such as a filter or pagination variable.

interface Parameter {
  variable: string;
  range: string | null;
  required: boolean;
  description: string;
  deprecated?: boolean;
}

FieldType

Enumerates the possible types for a field, such as string, integer, date, etc.

type FieldType =
  | "string"
  | "integer"
  | "negativeInteger"
  | "nonNegativeInteger"
  | "positiveInteger"
  | "nonPositiveInteger"
  | "number"
  | "decimal"
  | "double"
  | "float"
  | "boolean"
  | "date"
  | "dateTime"
  | "duration"
  | "time"
  | "byte"
  | "binary"
  | "hexBinary"
  | "base64Binary"
  | "array"
  | "object"
  | "email"
  | "url"
  | "uuid"
  | "password"
  | string;

Operation

Represents an operation (such as GET, POST, PUT, PATCH, DELETE) that can be performed on a resource.

interface Operation {
  name: string | null;
  type: "show" | "edit" | "delete" | "list" | "create" | null;
  method?: string | null;
  expects?: any | null;
  returns?: string | null;
  types?: string[] | null;
  deprecated?: boolean | null;
}

📖 OpenAPI Support

api-doc-parser applies a predictable set of rules when interpreting an OpenAPI document.
If a rule is not met, the resource concerned is silently skipped.

🧩 Support for other formats (JSON:API, AsyncAPI...)

API Doc Parser is designed to parse any API documentation format and convert it in the same intermediate representation. If you develop a parser for another format, please open a Pull Request to include it in the library.

🤝 Contributing

Contributions are welcome! To contribute:

1. Read our Code of Conduct.

2. Fork the repository and create a feature branch.

3. Ensure you have the latest version of pnpm installed.

4. Install dependencies

   pnpm install
   

5. Adhere to the code style and lint rules

   pnpm lint:fix
   

   pnpm format
   

6. Run tests

   pnpm test
   

7. Ensure type correctness

   pnpm typecheck
   

8. Submit a pull request with a clear description of your changes.

👥 Contributors

🌟 Star History

🙌 Credits

Created by Kévin Dunglas. Sponsored by Les-Tilleuls.coop.

🔒 License

This project is licensed under the MIT License - see the LICENSE file for details.