Code-first is an API design and software development approach where the application's source code is the primary source of truth and the API contract (OpenAPI document, GraphQL schema, gRPC proto, type definitions) is generated from that code via decorators, annotations, type inference, or runtime introspection. It contrasts with the design-first (or contract-first) approach in which a hand-authored OpenAPI/GraphQL/Proto contract is written first and code is scaffolded from it. Code-first approaches are widely used in TypeScript, Python, Java, Go, and C# ecosystems where strong type systems make schema generation reliable.
URL: Visit APIs.json URL
- Type: Index (Topic)
- Position: Consuming
- Access: 3rd-Party
- API Design
- Code Generation
- Code-First
- Decorators
- Development Methodology
- Software Architecture
- Type Safety
- Created: 2025-01-01
- Modified: 2026-04-26
| Framework | Language | Contract Generation |
|---|---|---|
| FastAPI | Python | OpenAPI 3.x from Pydantic models and type hints |
| NestJS | TypeScript | OpenAPI via @nestjs/swagger decorators |
| tRPC | TypeScript | End-to-end TypeScript types, no separate IDL |
| Hono RPC | TypeScript | TypeScript inference, optional OpenAPI via @hono/zod-openapi |
| Spring Boot + springdoc | Java/Kotlin | OpenAPI from JAX-RS/Spring annotations |
| Quarkus | Java/Kotlin | MicroProfile OpenAPI from JAX-RS annotations |
| Micronaut OpenAPI | Java/Kotlin | Compile-time AST inspection |
| ASP.NET Core | C# | Microsoft.AspNetCore.OpenApi / Swashbuckle |
| Huma | Go | OpenAPI from struct tags and reflection |
| Encore | Go/TypeScript | API contract inferred from typed handlers |
| zod-openapi | TypeScript | OpenAPI generated from Zod schemas |
| rswag | Ruby on Rails | OpenAPI from RSpec request specs |
| Scribe | PHP / Laravel | OpenAPI from controller introspection and PHPDoc |
| Pothos | TypeScript | GraphQL SDL from typed builders |
| grpc-gateway | Go | Proto + code; reverse-proxy to REST |
- Single source of truth eliminates contract/code drift
- Faster iteration - no separate OpenAPI editing step
- Strong type safety end-to-end (especially in TypeScript and Python)
- Familiar to backend engineers; low onboarding cost
- IDE-friendly - routes and types surface natively
- Contract changes are implicit and harder to review independently
- Risk of leaking implementation details into the public contract
- Cross-team or cross-organization governance is harder
- Generated specs often lack examples, descriptions, and security details
- Frontend or partner teams cannot start integration before code is written
- Internal services where the backend team owns producer and consumer
- Rapid product development with tight feedback loops
- TypeScript monorepos using tRPC or shared types
- Python / FastAPI services where Pydantic already models the domain
- Public APIs with diverse external consumers
- Government, banking, or other contract-bound API programs
- Multi-team programs where contract review precedes implementation
- SDK generation pipelines that need stable, reviewed schemas
- Wikipedia: Code First
- Postman: API-First vs Code-First
- Stoplight: API Design-First vs Code-First
- Swagger: Code-First vs Design-First
- OpenAPI Specification
This profile is a topic landscape, not a single API. No OpenAPI specification, JSON-LD vocabulary, Spectral ruleset, or Naftiko capability bundle is generated because there is no single contract to lint or describe; each framework above ships its own.
FN: Kin Lane
Email: kin@apievangelist.com