OpenAPI, Zod i Dokumentacja API

Co to jest OpenAPI i jak generować spec z kodu TypeScript?

OpenAPI (dawniej Swagger): standard opisu API REST. YAML lub JSON. Wersja 3.0 i 3.1 (JSON Schema kompatybilna). Opis: endpoints, parametry, request body, responses, auth, examples. Tooling: swagger-ui — interaktywna dokumentacja. Scalar — nowoczesna alternatywa dla Swagger UI. Redoc — czytelna dokumentacja. openapi-typescript — generuj TypeScript types z OpenAPI spec. Orval — generuj React Query / Axios hooks z OpenAPI. Dwa podejścia: Code-first (generate spec z kodu): Express + TSDoc -> OpenAPI. Hono Zod OpenAPI. FastAPI (Python) pattern dla TS. tsoa — TypeScript -> OpenAPI. NestJS @nestjs/swagger. Contract-first (spec najpierw, potem kod): piszesz YAML/JSON. Generujesz server stub + client. Lepsza kontrola nad API. Zod + OpenAPI: @asteasolutions/zod-to-openapi. Definiuj schema w Zod. Rejestruj jako OpenAPI components. Generuj spec automatycznie. z.object({name: z.string()}).openapi({example: {name: 'Adam'}}). Hono Zod OpenAPI: @hono/zod-openapi. app.openapi(route, handler). Automatyczna walidacja + generowanie spec. /doc endpoint z Scalar UI. Korzyści code-first: jeden source of truth. Zawsze aktualny spec. TypeScript + runtime walidacja.

tRPC vs OpenAPI — kiedy wybrać co?

tRPC: end-to-end type safety bez schematu. TypeScript inference. Tylko TypeScript clients. Doskonały dla monorepo (Next.js full-stack). Brak interoperability z non-TS clients. Brak REST semantyki. Trudny do testowania z Postman. OpenAPI (z Zod): language-agnostic. REST standard. Swagger/Scalar UI. Generuj clients w dowolnym języku. Lepsza dla public API. Lepsza dla microservices (różne języki). tRPC-OpenAPI: @trpc/openapi package. Eksponuj tRPC jako REST + OpenAPI. Najlepsze z obu światów. Ale dodatkowa kompleksowość. GraphQL vs REST vs tRPC: GraphQL — elastyczne queries, N+1 problem, overkill dla prostego API. REST + OpenAPI — standard, language-agnostic, caching. tRPC — max DX dla TS monorepo, brak overhead. Kiedy OpenAPI: zewnętrzni konsumenci API. Mobile apps (iOS/Kotlin). Microservices różne języki. Public API z dokumentacją. Kiedy tRPC: wewnętrzny API w TS monorepo. Next.js full-stack. Szybki development bez schematu. Kiedy GraphQL: skomplikowane relacje danych. Mobile + web z różnymi potrzebami. Fragmenty danych. API Gateway pattern: OpenAPI spec jako kontrakt. API Gateway (Kong, AWS) waliduje request. Backend nie musi walidować. Zodios: klient HTTP z Zod schema. import {Zodios} from '@zodios/core'. Fully typed z OpenAPI spec. Alternatywa dla Axios + ręcznych types.

Orval i openapi-typescript — generowanie klientów z OpenAPI?

openapi-typescript: generuj TypeScript types z OpenAPI spec. npx openapi-typescript openapi.yaml -o schema.ts. Generuje: paths interface. components.schemas. Czyste types (nie klasy). openapi-fetch: type-safe fetch z wygenerowanych types. import createClient from 'openapi-fetch'. const client = createClient({baseUrl: 'https://api.example.com'}). const {data, error} = await client.GET('/users/{id}', {params: {path: {id: 1}}}). Pełna type inference z OpenAPI spec. Orval: generuj React Query hooks, Axios, SWR. orval.config.ts: export default {api: {output: {mode: 'tags-split', target: 'src/api', schemas: 'src/api/model', client: 'react-query', httpClient: 'axios'}, input: {target: 'openapi.yaml'}}}. npx orval. Generuje: useGetUsers, useCreateUser hooks. Axios instance. TypeScript types. Auto-update przy zmianie spec. Swagger Codegen / OpenAPI Generator: generuj klientów w 30+ językach. Java, Python, Go, Ruby, PHP. Dla non-JS teams. msw-auto-mock: generuj MSW handlers z OpenAPI spec. Automatyczne mocki do testowania. Scalar: nowoczesna doc UI. @scalar/nextjs-api-reference. Beautiful API explorer. Dark mode, search, try-it-out. Lepszy od Swagger UI. Zastępuje Swagger UI w większości projektów. NestJS Swagger: @ApiProperty() decoratory. SwaggerModule.setup('/api', app, document). Automatyczne generowanie z decoratorów. Hono + Zod OpenAPI: najprostsze code-first setup dla TS backend.

API versioning i backward compatibility — best practices?

Versioning strategie: URL versioning: /v1/users, /v2/users. Najprostsze. Najbardziej widoczne. Header versioning: Accept: application/vnd.api+json;version=2. Czystsze URL. Trudniejsze w testowaniu. Query param: /users?version=2. Prosta implementacja. Semantic Versioning dla API: MAJOR — breaking changes. MINOR — backward compatible. PATCH — bug fixes. Breaking changes: usunięcie pola. Zmiana typu pola (string -> int). Zmiana wymagalności (optional -> required). Zmiana semantyki endpoint. Non-breaking changes: dodanie opcjonalnego pola. Dodanie nowego endpoint. Dodanie nowej wartości enum (ostrożnie). Deprecation strategy: deprecation header. Sunset: data usunięcia. Changelog. Migracja guides. Zod i optional fields: z.object({name: z.string(), newField: z.optional(z.string())}). Additive changes są safe. Backward compatibility testing: consumer-driven contract testing. Pact — contract testing library. Consumer definiuje contract. Provider weryfikuje. Versionless API (alternatywa): GraphQL — klient pyta tylko o potrzebne pola. tRPC — versioning przez procedure names. Avoid global versioning. OpenAPI Diff: oasdiff narzędzie. Automatyczne wykrycie breaking changes. W CI/CD pipeline. Versioning w Next.js: route groups: (v1), (v2). Middleware: rewrite do odpowiedniej wersji. API evolution tips: expand, then contract. Dodaj nowe pola, potem deprecate stare. Grace period minimum 6 miesięcy.

API dokumentacja — Scalar, Swagger UI, Redoc i Storybook?

Scalar: nowoczesna, piękna API dokumentacja. Open source. Built-in try-it-out. Dark mode. Code examples (curl, JS, Python, Go). Search. CDN: cdn.jsdelivr.net/npm/@scalar/api-reference. @scalar/nextjs-api-reference — Next.js integracja. @scalar/fastify-api-reference, @scalar/hono-api-reference. Swagger UI: klasyczny. Funkcjonalny ale przestarzały wygląd. Darmowy, open source. Trudna customizacja. Redoc: czytelna, trzykolumnowa. Read-only (brak try-it-out). Dobre dla dokumentacji public. Szybki rendering dużych spec. StopLight Elements: zaawansowane, enterprise. Try-it-out. Wbudowany. Postman: kolekcje requests. Collaboration. Monitoring. Mock servers. Newman — CLI dla CI. Insomnia: lekki Postman alternative. Open source core. GraphQL + REST. Hoppscotch: open source, web-based. Dokumentacja jako kod (Docs-as-Code): OpenAPI spec w repozytorium. CI generuje dokumentację. GitHub Pages lub własny hosting. Versioning dokumentacji z kodem. Best practices: przykłady dla każdego endpoint. Error response schemas. Authentication dokumentacja. Rate limiting info. Changelog. Storybook + API mocking: Storybook + MSW handlers. Mockuj API w komponentach. Argstypes dla API responses. Visual testing z różnymi stanami API. Readme-driven development: najpierw README. Opisz API przed implementacją. API contract jako spec.

Wyślij zapytanie