1# OpenAPI Code-First Generation and Tooling
2 
3Advanced patterns for generating OpenAPI specs from code (Python/FastAPI, TypeScript/tsoa), validation, linting, and SDK generation.
4 
5## Template 2: Code-First Generation (Python/FastAPI)
6 
7```python
8# FastAPI with automatic OpenAPI generation
9from fastapi import FastAPI, HTTPException, Query, Path, Depends
10from pydantic import BaseModel, Field, EmailStr
11from typing import Optional, List
12from datetime import datetime
13from uuid import UUID
14from enum import Enum
15 
16app = FastAPI(
17    title="User Management API",
18    description="API for managing users and profiles",
19    version="2.0.0",
20    openapi_tags=[
21        {"name": "Users", "description": "User operations"},
22        {"name": "Profiles", "description": "Profile operations"},
23    ],
24    servers=[
25        {"url": "https://api.example.com/v2", "description": "Production"},
26        {"url": "http://localhost:8000", "description": "Development"},
27    ],
28)
29 
30# Enums
31class UserStatus(str, Enum):
32    active = "active"
33    inactive = "inactive"
34    suspended = "suspended"
35    pending = "pending"
36 
37class UserRole(str, Enum):
38    user = "user"
39    moderator = "moderator"
40    admin = "admin"
41 
42# Models
43class UserBase(BaseModel):
44    email: EmailStr = Field(..., description="User email address")
45    name: str = Field(..., min_length=1, max_length=100, description="Display name")
46 
47class UserCreate(UserBase):
48    role: UserRole = Field(default=UserRole.user)
49    metadata: Optional[dict] = Field(default=None, description="Custom metadata")
50 
51    model_config = {
52        "json_schema_extra": {
53            "examples": [
54                {
55                    "email": "[email protected]",
56                    "name": "John Doe",
57                    "role": "user"
58                }
59            ]
60        }
61    }
62 
63class UserUpdate(BaseModel):
64    name: Optional[str] = Field(None, min_length=1, max_length=100)
65    status: Optional[UserStatus] = None
66    role: Optional[UserRole] = None
67    metadata: Optional[dict] = None
68 
69class User(UserBase):
70    id: UUID = Field(..., description="Unique identifier")
71    status: UserStatus
72    role: UserRole
73    avatar: Optional[str] = Field(None, description="Avatar URL")
74    metadata: Optional[dict] = None
75    created_at: datetime = Field(..., alias="createdAt")
76    updated_at: Optional[datetime] = Field(None, alias="updatedAt")
77 
78    model_config = {"populate_by_name": True}
79 
80class Pagination(BaseModel):
81    page: int = Field(..., ge=1)
82    limit: int = Field(..., ge=1, le=100)
83    total: int = Field(..., ge=0)
84    total_pages: int = Field(..., ge=0, alias="totalPages")
85    has_next: bool = Field(..., alias="hasNext")
86    has_prev: bool = Field(..., alias="hasPrev")
87 
88class UserListResponse(BaseModel):
89    data: List[User]
90    pagination: Pagination
91 
92class ErrorDetail(BaseModel):
93    field: str
94    message: str
95 
96class ErrorResponse(BaseModel):
97    code: str = Field(..., description="Error code")
98    message: str = Field(..., description="Error message")
99    details: Optional[List[ErrorDetail]] = None
100    request_id: Optional[str] = Field(None, alias="requestId")
101 
102# Endpoints
103@app.get(
104    "/users",
105    response_model=UserListResponse,
106    tags=["Users"],
107    summary="List all users",
108    description="Returns a paginated list of users with optional filtering.",
109    responses={
110        400: {"model": ErrorResponse, "description": "Invalid request"},
111        401: {"model": ErrorResponse, "description": "Unauthorized"},
112    },
113)
114async def list_users(
115    page: int = Query(1, ge=1, description="Page number"),
116    limit: int = Query(20, ge=1, le=100, description="Items per page"),
117    status: Optional[UserStatus] = Query(None, description="Filter by status"),
118    search: Optional[str] = Query(None, min_length=2, max_length=100),
119):
120    """
121    List users with pagination and filtering.
122 
123    - **page**: Page number (1-based)
124    - **limit**: Number of items per page (max 100)
125    - **status**: Filter by user status
126    - **search**: Search by name or email
127    """
128    # Implementation
129    pass
130 
131@app.post(
132    "/users",
133    response_model=User,
134    status_code=201,
135    tags=["Users"],
136    summary="Create a new user",
137    responses={
138        400: {"model": ErrorResponse},
139        409: {"model": ErrorResponse, "description": "Email already exists"},
140    },
141)
142async def create_user(user: UserCreate):
143    """Create a new user and send welcome email."""
144    pass
145 
146@app.get(
147    "/users/{user_id}",
148    response_model=User,
149    tags=["Users"],
150    summary="Get user by ID",
151    responses={404: {"model": ErrorResponse}},
152)
153async def get_user(
154    user_id: UUID = Path(..., description="User ID"),
155):
156    """Retrieve a specific user by their ID."""
157    pass
158 
159@app.patch(
160    "/users/{user_id}",
161    response_model=User,
162    tags=["Users"],
163    summary="Update user",
164    responses={
165        400: {"model": ErrorResponse},
166        404: {"model": ErrorResponse},
167    },
168)
169async def update_user(
170    user_id: UUID = Path(..., description="User ID"),
171    user: UserUpdate = ...,
172):
173    """Update user attributes."""
174    pass
175 
176@app.delete(
177    "/users/{user_id}",
178    status_code=204,
179    tags=["Users", "Admin"],
180    summary="Delete user",
181    responses={404: {"model": ErrorResponse}},
182)
183async def delete_user(
184    user_id: UUID = Path(..., description="User ID"),
185):
186    """Permanently delete a user."""
187    pass
188 
189# Export OpenAPI spec
190if __name__ == "__main__":
191    import json
192    print(json.dumps(app.openapi(), indent=2))
193```
194 
195## Template 3: Code-First (TypeScript/Express with tsoa)
196 
197```typescript
198// tsoa generates OpenAPI from TypeScript decorators
199 
200import {
201  Controller,
202  Get,
203  Post,
204  Patch,
205  Delete,
206  Route,
207  Path,
208  Query,
209  Body,
210  Response,
211  SuccessResponse,
212  Tags,
213  Security,
214  Example,
215} from "tsoa";
216 
217// Models
218interface User {
219  /** Unique identifier */
220  id: string;
221  /** User email address */
222  email: string;
223  /** Display name */
224  name: string;
225  status: UserStatus;
226  role: UserRole;
227  /** Avatar URL */
228  avatar?: string;
229  /** Custom metadata */
230  metadata?: Record<string, unknown>;
231  createdAt: Date;
232  updatedAt?: Date;
233}
234 
235enum UserStatus {
236  Active = "active",
237  Inactive = "inactive",
238  Suspended = "suspended",
239  Pending = "pending",
240}
241 
242enum UserRole {
243  User = "user",
244  Moderator = "moderator",
245  Admin = "admin",
246}
247 
248interface CreateUserRequest {
249  email: string;
250  name: string;
251  role?: UserRole;
252  metadata?: Record<string, unknown>;
253}
254 
255interface UpdateUserRequest {
256  name?: string;
257  status?: UserStatus;
258  role?: UserRole;
259  metadata?: Record<string, unknown>;
260}
261 
262interface Pagination {
263  page: number;
264  limit: number;
265  total: number;
266  totalPages: number;
267  hasNext: boolean;
268  hasPrev: boolean;
269}
270 
271interface UserListResponse {
272  data: User[];
273  pagination: Pagination;
274}
275 
276interface ErrorResponse {
277  code: string;
278  message: string;
279  details?: { field: string; message: string }[];
280  requestId?: string;
281}
282 
283@Route("users")
284@Tags("Users")
285export class UsersController extends Controller {
286  /**
287   * List all users with pagination and filtering
288   * @param page Page number (1-based)
289   * @param limit Items per page (max 100)
290   * @param status Filter by user status
291   * @param search Search by name or email
292   */
293  @Get()
294  @Security("bearerAuth")
295  @Response<ErrorResponse>(400, "Invalid request")
296  @Response<ErrorResponse>(401, "Unauthorized")
297  @Example<UserListResponse>({
298    data: [
299      {
300        id: "550e8400-e29b-41d4-a716-446655440000",
301        email: "[email protected]",
302        name: "John Doe",
303        status: UserStatus.Active,
304        role: UserRole.User,
305        createdAt: new Date("2024-01-15T10:30:00Z"),
306      },
307    ],
308    pagination: {
309      page: 1,
310      limit: 20,
311      total: 1,
312      totalPages: 1,
313      hasNext: false,
314      hasPrev: false,
315    },
316  })
317  public async listUsers(
318    @Query() page: number = 1,
319    @Query() limit: number = 20,
320    @Query() status?: UserStatus,
321    @Query() search?: string,
322  ): Promise<UserListResponse> {
323    // Implementation
324    throw new Error("Not implemented");
325  }
326 
327  /**
328   * Create a new user
329   */
330  @Post()
331  @Security("bearerAuth")
332  @SuccessResponse(201, "Created")
333  @Response<ErrorResponse>(400, "Invalid request")
334  @Response<ErrorResponse>(409, "Email already exists")
335  public async createUser(@Body() body: CreateUserRequest): Promise<User> {
336    this.setStatus(201);
337    throw new Error("Not implemented");
338  }
339 
340  /**
341   * Get user by ID
342   * @param userId User ID
343   */
344  @Get("{userId}")
345  @Security("bearerAuth")
346  @Response<ErrorResponse>(404, "User not found")
347  public async getUser(@Path() userId: string): Promise<User> {
348    throw new Error("Not implemented");
349  }
350 
351  /**
352   * Update user attributes
353   * @param userId User ID
354   */
355  @Patch("{userId}")
356  @Security("bearerAuth")
357  @Response<ErrorResponse>(400, "Invalid request")
358  @Response<ErrorResponse>(404, "User not found")
359  public async updateUser(
360    @Path() userId: string,
361    @Body() body: UpdateUserRequest,
362  ): Promise<User> {
363    throw new Error("Not implemented");
364  }
365 
366  /**
367   * Delete user
368   * @param userId User ID
369   */
370  @Delete("{userId}")
371  @Tags("Users", "Admin")
372  @Security("bearerAuth")
373  @SuccessResponse(204, "Deleted")
374  @Response<ErrorResponse>(404, "User not found")
375  public async deleteUser(@Path() userId: string): Promise<void> {
376    this.setStatus(204);
377  }
378}
379```
380 
381## Template 4: Validation & Linting
382 
383```bash
384# Install validation tools
385npm install -g @stoplight/spectral-cli
386npm install -g @redocly/cli
387 
388# Spectral ruleset (.spectral.yaml)
389cat > .spectral.yaml << 'EOF'
390extends: ["spectral:oas", "spectral:asyncapi"]
391 
392rules:
393  # Enforce operation IDs
394  operation-operationId: error
395 
396  # Require descriptions
397  operation-description: warn
398  info-description: error
399 
400  # Naming conventions
401  operation-operationId-valid-in-url: true
402 
403  # Security
404  operation-security-defined: error
405 
406  # Response codes
407  operation-success-response: error
408 
409  # Custom rules
410  path-params-snake-case:
411    description: Path parameters should be snake_case
412    severity: warn
413    given: "$.paths[*].parameters[?(@.in == 'path')].name"
414    then:
415      function: pattern
416      functionOptions:
417        match: "^[a-z][a-z0-9_]*$"
418 
419  schema-properties-camelCase:
420    description: Schema properties should be camelCase
421    severity: warn
422    given: "$.components.schemas[*].properties[*]~"
423    then:
424      function: casing
425      functionOptions:
426        type: camel
427EOF
428 
429# Run Spectral
430spectral lint openapi.yaml
431 
432# Redocly config (redocly.yaml)
433cat > redocly.yaml << 'EOF'
434extends:
435  - recommended
436 
437rules:
438  no-invalid-media-type-examples: error
439  no-invalid-schema-examples: error
440  operation-4xx-response: warn
441  request-mime-type:
442    severity: error
443    allowedValues:
444      - application/json
445  response-mime-type:
446    severity: error
447    allowedValues:
448      - application/json
449      - application/problem+json
450 
451theme:
452  openapi:
453    generateCodeSamples:
454      languages:
455        - lang: curl
456        - lang: python
457        - lang: javascript
458EOF
459 
460# Run Redocly
461redocly lint openapi.yaml
462redocly bundle openapi.yaml -o bundled.yaml
463redocly preview-docs openapi.yaml
464```
465 
466## SDK Generation
467 
468```bash
469# OpenAPI Generator
470npm install -g @openapitools/openapi-generator-cli
471 
472# Generate TypeScript client
473openapi-generator-cli generate \
474  -i openapi.yaml \
475  -g typescript-fetch \
476  -o ./generated/typescript-client \
477  --additional-properties=supportsES6=true,npmName=@myorg/api-client
478 
479# Generate Python client
480openapi-generator-cli generate \
481  -i openapi.yaml \
482  -g python \
483  -o ./generated/python-client \
484  --additional-properties=packageName=api_client
485 
486# Generate Go client
487openapi-generator-cli generate \
488  -i openapi.yaml \
489  -g go \
490  -o ./generated/go-client
491```
492