OpenAPI & .NET: You're Doing It Wrong!
summary
Argument: stop auto-generating Swagger from controllers and handwrite OpenAPI as the source of truth. Concrete workflow: use OpenAPI 3.1 YAML checked into GitHub, run a bundler (Redocly or a .NET bundler) in GitHub Actions to produce a single spec, publish static docs with Elements or Redocly, and generate clients or skeleton servers. At a UK financial shop with ~20 teams this cuts duplicated markdown, produces real examples and descriptions, enables validations, analyzers and tests, and surfaces mismatch warnings early.
AI-written summary · about
chapters (15)
- 0:00🚀 Build Stuff Conference – Get Your Tickets!
- 0:35Introduction: What is OpenAPI and Why Does It Matter?
- 3:00The Flaws of Auto-Generated OpenAPI Docs
- 5:28OpenAPI in the .NET Ecosystem: Swashbuckle vs. Handwritten Specs
- 8:01A Better Way: Writing OpenAPI Specs by Hand
- 9:14Real-World Example: Implementing OpenAPI in a Financial Microservices System
- 12:05The Role of OpenAPI in API Design and Communication
- 15:00Why Handwriting OpenAPI Spec is Better Than Auto-Generation
- 18:47Exploring the OpenAPI 3.0 vs. 3.1 Changes
- 22:30Writing and Structuring OpenAPI YAML Files by Hand
- 27:00Using GitHub Actions to Automate Documentation Generation
- 30:00Integrating OpenAPI into Your Development Workflow
- 33:15Using OpenAPI with Swagger UI and Elements for Interactive Docs
- 37:00How OpenAPI Fits with Other Tools and API Models (e.g., gRPC, AsyncAPI)
- 41:10Final Thoughts and Best Practices for OpenAPI in .NET
related talks
01h 01mOpenAPI & .NET: You're Doing It Wrong
19mSecure and accelerate APIs' lifecycle with the OpenAPI specification
37mAutomation++ - Building an Enterprise API Economy from scratch
35mDocumenting APIs: new era, same craft
35mAPI-First! Contract-First! Make API development great again!
40mThe Four Stages of OpenAPI
31mOpenAPIs are everywhere
30mOne Spec to Rule them all - OpenAPI in Action