code-first/apis.yml at main · api-evangelist/code-first · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
aid: code-first
url: >-
  https://raw.githubusercontent.com/api-evangelist/code-first/refs/heads/main/apis.yml
name: Code First
tags:
  - API Design
  - Code Generation
  - Code-First
  - Decorators
  - Development Methodology
  - Software Architecture
  - Type Safety
type: Index
accessModel:
  pricing: unknown
  onboarding: unknown
  trial: false
  try_now: false
  public: false
  label: Unknown
  confidence: low
  source: []
  generated: '2026-07-22'
  method: derived
image: https://kinlane-images.s3.amazonaws.com/shared/apis-json/icons/code-first.png
access: 3rd-Party
kind: topic
created: '2025-01-01'
modified: '2026-04-26'
position: Consumer
description: >-
  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.
x-related-topics:
  - design-first
  - api-design
  - openapi
  - graphql
  - trpc
  - type-safety
  - schema-generation
x-key-frameworks:
  - name: FastAPI
    language: Python
    contract: OpenAPI 3.x generated from Pydantic models and type hints
    url: https://fastapi.tiangolo.com/
  - name: NestJS
    language: TypeScript
    contract: OpenAPI generated via @nestjs/swagger decorators
    url: https://docs.nestjs.com/openapi/introduction
  - name: tRPC
    language: TypeScript
    contract: End-to-end TypeScript types, no separate IDL
    url: https://trpc.io/
  - name: Hono RPC
    language: TypeScript
    contract: TypeScript inference, optional OpenAPI via @hono/zod-openapi
    url: https://hono.dev/docs/guides/rpc
  - name: Spring Boot + springdoc-openapi
    language: Java/Kotlin
    contract: OpenAPI generated from JAX-RS/Spring annotations
    url: https://springdoc.org/
  - name: Quarkus
    language: Java/Kotlin
    contract: MicroProfile OpenAPI from JAX-RS annotations
    url: https://quarkus.io/guides/openapi-swaggerui
  - name: Micronaut
    language: Java/Kotlin
    contract: OpenAPI from compile-time AST inspection
    url: https://micronaut-projects.github.io/micronaut-openapi/
  - name: ASP.NET Core (Minimal APIs / Controllers)
    language: C#
    contract: OpenAPI via Microsoft.AspNetCore.OpenApi or Swashbuckle
    url: https://learn.microsoft.com/aspnet/core/fundamentals/openapi
  - name: Go - chi-openapi / go-swagger / huma
    language: Go
    contract: OpenAPI from struct tags and reflection
    url: https://huma.rocks/
  - name: Encore
    language: Go/TypeScript
    contract: API contract inferred from typed handlers
    url: https://encore.dev/
  - name: Express + zod-openapi
    language: TypeScript
    contract: OpenAPI generated from zod schemas
    url: https://github.com/asteasolutions/zod-to-openapi
  - name: Ruby on Rails + rswag
    language: Ruby
    contract: OpenAPI from RSpec request specs
    url: https://github.com/rswag/rswag
  - name: Laravel - Scribe
    language: PHP
    contract: OpenAPI from controller introspection and PHPDoc
    url: https://scribe.knuckles.wtf/
  - name: GraphQL Nexus / Pothos
    language: TypeScript
    contract: GraphQL SDL generated from typed builders
    url: https://pothos-graphql.dev/
  - name: gRPC + tonic / grpc-gateway
    language: Rust/Go
    contract: Proto + code; debate over which is "first"
    url: https://github.com/grpc-ecosystem/grpc-gateway
x-tradeoffs:
  pros:
    - Single source of truth eliminates contract/code drift
    - Faster iteration - no separate OpenAPI editing step
    - Strong type safety end-to-end (especially in TS/Python)
    - Familiar to backend engineers; lower onboarding cost
    - Tooling-friendly - IDEs surface routes and types natively
  cons:
    - Contract changes are implicit; harder to review independently
    - Risk of leaking implementation details into the public contract
    - Cross-team or cross-organization governance is harder
    - Generated specs sometimes lack examples, descriptions, security
    - Frontend or partner teams cannot start integration before code is written
x-when-to-use:
  - Internal services where 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 domain
x-when-to-avoid:
  - 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
apis: []
common:
  - type: Reference
    url: https://en.wikipedia.org/wiki/Code_first
  - type: Article
    url: https://blog.postman.com/api-first-vs-code-first/
  - type: Article
    url: https://blog.stoplight.io/api-design-first-vs-code-first
  - type: Article
    url: https://swagger.io/blog/code-first-vs-design-first-api/
  - type: Specification
    url: https://spec.openapis.org/
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com
specificationVersion: '0.19'