OpenAPI & .NET: You're Doing It Wrong

on YouTube ↗57m

" summary

Swashbuckle or NSwag auto-generators are not the source of truth; instead write and maintain the OpenAPI file manually in source control (prefer YAML) so design and docs live together. Use OpenAPI 3.0, linters and bundlers (redocly) to produce a single spec, publish static docs via simple GitHub Actions, and expose live docs with tools like Redoc and Elements. A .NET NuGet (openapi.web) can serve SwaggerUI and Elements and analyzers plus codegen can validate and regenerate stubs so breaking changes fail to compile.

AI-written summary · about

" chapters (5)

1. 0:00Start
2. 2:58OpenAPI Versions
3. 27:17Components
4. 40:18Tools
5. 52:58Packages

" related talks

• 53mUncovering Swagger/OpenAPIKevin Dockx · .NET Fest 2019
• 19mSecure and accelerate APIs' lifecycle with the OpenAPI specificationArnaud Lauret · Nordic APIs Platform Summit 2016
• 19mAutomate your API to perfectionChris Ward · Apidays LIVE Paris 2020
• 21mLet there be docs!Svyatoslav Kryukov · Friendly.rb 2023
• 27mGetting developers hooked on your APINicolas Garnier · Codemotion Amsterdam 2016
• 59mHandy Tools for Designing Great Web APIsMike Amundsen · NDC Porto 2019
• 38mZen And The Art Of Automanually Creating API Documentation - An Inquiry Into ProcessDan Grabski · Write the Docs Portland 2023
• 34mShuffle ball change: Sashay your way to clearer API documentationRachael Stavchansky · Write the Docs Portland 2021