All 15 API Documentation with Swagger/OpenAPI questions
More in API Documentation with Swagger/OpenAPI
How do you document authentication requirements (like a JWT bearer token) in Swagger UI so users can test authenticated endpoints interactively? How does the newer built-in Microsoft.AspNetCore.OpenApi package (introduced in .NET 9) differ from the third-party Swashbuckle package? How would you exclude specific endpoints or entire controllers from appearing in the generated Swagger documentation? How would you generate a client SDK automatically from an ASP.NET Core API's OpenAPI specification? How do you document and test webhook or callback endpoints (server-initiated calls to a client-registered URL) in OpenAPI 3.1? How does schema reuse work in OpenAPI (via $ref and components/schemas), and how does Swashbuckle handle types shared across multiple endpoints?
Advertisement
ASP.NET Core › API Documentation with Swagger/OpenAPI

What is 'design-first' versus 'code-first' API development, and how does OpenAPI tooling support each approach?

Advanced

Answer

Code-first (the default with Swashbuckle) generates the OpenAPI spec automatically from your existing C# code, meaning the code is the source of truth and documentation follows implementation. Design-first instead starts by hand-authoring the OpenAPI YAML/JSON spec as the contract, then uses code generation tools (like NSwag's server stub generation) to scaffold matching controller interfaces from that spec, letting API design and stakeholder review happen before any implementation code is written -- valuable for API-first organizations needing early contract agreement across teams.
# Design-first: author the spec first
# api-spec.yaml defines the full contract

# Generate server stubs from the spec
nswag openapi2cscontroller /input:api-spec.yaml /output:GeneratedControllers.cs
# Developers then implement the generated interface's logic
Real-world example A large enterprise with separate frontend and backend teams adopts design-first API development, having both teams review and agree on an OpenAPI spec before backend implementation begins, avoiding costly late-stage contract renegotiation.

Common follow-ups: What are the trade-offs of design-first for smaller teams or rapidly iterating projects?;How do you keep a design-first spec and its generated stubs in sync as requirements evolve?

Controllers vs Minimal APIs;RESTful Web APIs & Controllers
All 15 API Documentation with Swagger/OpenAPI questions