openapi-first

Generate OpenAPI specs from Spring Boot for TypeScript frontend clients.

Updated Jan 23, 2025

Search Tags:#openapi #type-safety #spring-boot #code-generation #backend-frontend #api-contract

Ready to run

npx skills add https://github.com/ymkz/demo-monorepo --skill openapi-first

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: openapi-first
Source: https://github.com/ymkz/demo-monorepo/tree/main/.agents/skills/openapi-first
Command: npx skills add https://github.com/ymkz/demo-monorepo --skill openapi-first

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

OpenAPI-first development helps align backend and frontend teams by generating the OpenAPI contract from the backend and consuming it on the frontend to ensure type safety and contract accuracy.

Core Features & Use Cases

Backend generation of OpenAPI docs (openapi.json) from Spring Boot with Springdoc.
Frontend code generation of TypeScript types and API clients using @hey-api/openapi-ts.
Single source of truth for API contracts, enabling safe end-to-end development across services.

Quick Start

Configure backend OpenAPI generation first, then run the frontend generator to produce type-safe clients.

Frequently Asked Questions about openapi-first

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I ensure end-to-end type safety between Spring Boot and TypeScript?▼

End-to-end type safety is ensured by generating a shared OpenAPI contract from Spring Boot and using it to generate TypeScript types and API clients for the frontend. This establishes a single source of truth for API definitions across teams.

How do I generate TypeScript API clients from a Spring Boot OpenAPI spec?▼

You can generate TypeScript API clients from a Spring Boot OpenAPI spec by configuring Springdoc to produce openapi.json, then running the @hey-api/openapi-ts frontend tooling to generate the types. This reproducible workflow guarantees contract accuracy.

What is an OpenAPI-first workflow for backend and frontend integration?▼

An OpenAPI-first workflow for backend and frontend integration derives the API contract from the backend to guarantee type-safe frontend integration. It aligns teams by making the generated OpenAPI spec the single source of truth for API definitions.

Do I need Springdoc OpenAPI to use an OpenAPI-first TypeScript workflow?▼

Yes, Springdoc OpenAPI is required to generate the openapi.json documentation from your Spring Boot backend. This backend generation step is necessary before running the frontend code generator to produce type-safe clients.

Can I use this approach if my frontend is not built with TypeScript?▼

No, this OpenAPI-first approach specifically targets frontend projects using TypeScript. It relies on generating TypeScript types and API clients using @hey-api/openapi-ts to guarantee type-safe frontend integration.

Why use a generated OpenAPI contract instead of manually defining API types?▼

Using a generated OpenAPI contract instead of manually defining types prevents contract drift between services. Generating the spec from the backend ensures a single source of truth, enabling safe end-to-end development across teams.