FIRST CHTools

FIRST CH TOOLS / Development / 73 OPENAPI DOC GENERATOR

OpenAPI → Markdown Docs & TypeScript Types

Turns an OpenAPI / Swagger specification (JSON or YAML) into API documentation in Markdown (Japanese or English) and TypeScript type definitions (.ts). You get the endpoint list, parameter tables, request and response examples and schema tables; copy either one or save it as a file. The specification is read on this page only and never leaves your device.

1 — Specification (OpenAPI / Swagger)

Paste the specification or drop a file onto this box (up to 20 MB). Files are read on your device and never uploaded.
—
Spec version
0
Endpoints
0
Schemas
—
Generation time

2 — API documentation (Markdown)

Endpoint list, parameter tables, request and response examples, then schema tables, in that order. Paste it straight into GitHub, Notion or a wiki.

3 — TypeScript type definitions

Schemas become an interface or a type, enums become unions of string literals, and nullable becomes | null. Type declarations only — no runtime code.
Checks
  • Paste a specification, or press “Load sample”.

Parsing the specification and building the docs and types all happen on this page. The specification you paste or the file you choose is never sent to a server, so internal API specs are fine to use. Nothing is taken from URL parameters.

How to Use

  1. Add the specificationPaste the contents of openapi.yaml or swagger.json, or open or drop the file. OpenAPI 3.0 / 3.1 and Swagger 2.0 are read, in JSON or YAML.
  2. Pick the language and outputsChoose Japanese or English for the document, whether to build response examples, and whether to emit per-endpoint types. Output is generated as soon as the spec is in.
  3. Copy or saveSave the Markdown as .md and the types as .ts. Drop the types into something like src/types/ in your front end and import them.

About This Tool

This tool turns an OpenAPI (formerly Swagger) specification into two things at once: readable API documentation in Markdown — in Japanese or English — and TypeScript type definitions for the front end. Parsing and string building happen only on this page, for teams that would rather not upload their specification to an outside service.

The documentation (Markdown) starts with base URLs, the endpoint list and the authentication schemes, then gives each endpoint a parameter table (name, location, type, required, description), the request body, a response table and examples, and ends with a property table for each schema. Endpoints are grouped by tag when tags exist. Examples written in the spec (example / examples) come first; otherwise one is built from the schema’s type, format, enum and default, and the heading says so. Headings and fixed phrases follow the chosen language; descriptions are kept exactly as written in the spec (nothing is translated).

The TypeScript definitions turn each entry in components.schemas (definitions in Swagger 2.0) into an export interface or export type. Properties not listed in required get ?; enum becomes "a" | "b", allOf becomes &, oneOf / anyOf become |, nullable (or type: [..., "null"] in 3.1) becomes | null, readOnly becomes readonly and format: binary becomes Blob. Descriptions, formats, defaults and deprecation are kept as JSDoc comments, so they show up in editor hints. Per-endpoint types are named …Params, …RequestBody and …Response after the operationId (or the method and path). The output has been checked to compile under TypeScript --strict with real specifications, including the public GitHub and Stripe ones.

Limits: a $ref pointing to another file or URL (such as ./schemas/user.yaml) is not fetched; its type becomes unknown and you are told. Use a bundled, single-file specification. No SDKs or client code that actually calls the API are generated — type declarations only. YAML is read as YAML 1.2, including anchors, aliases and merge keys; syntax errors stop with the line and column. For converting or formatting YAML and JSON themselves use JSON ⇄ YAML Converter; to turn JSON responses into a table, CSV/TSV ⇄ JSON Converter; to tidy Markdown tables, Markdown Table Generator.

Other Tools