In this #OneDevQuestion video, Mike Kistler shares his favorite .NET 9 OpenAPI feature—build-time doc generation—and its developer benefits.

Summary

In this #OneDevQuestion segment, Mike Kistler highlights his favorite OpenAPI feature introduced in .NET 9: build-time documentation generation. Traditional approaches often involve serving OpenAPI (Swagger) documentation directly from a running application, which can add overhead and slow down certain development or CI workflows.

Build-Time OpenAPI Documentation

  • Concept: Instead of generating and hosting OpenAPI docs at runtime, .NET 9 allows for build-time doc generation.
  • Benefits:
    • Performance: No need to serve docs from the app, reducing production footprint and potential exposure.
    • Workflow Improvement: Developers can use the generated docs locally for tasks such as linting, static analysis, and code generation.
    • Tool Integration: Tools like Spectral can utilize the documentation to ensure adherence to best practices and enforce API conventions.
    • Automation: Enhanced suitability for CI/CD pipelines and automation scenarios, enabling static validation and codegen.
  • Best Practices: Build-time generation fits well with modern development workflows, promoting reproducibility and consistency across teams.

Key Uses

  • Linting: Catch API design issues early using linting tools.
  • Code Generation: Automate client or server code creation from OpenAPI docs without running the app.
  • Conventions Enforcement: Use tools (e.g. Spectral) to maintain organizational or industry standards.

Conclusion

.NET 9’s build-time OpenAPI generation streamlines development by empowering developers during the build stage, improving automation potential, and fostering adherence to high-quality API design standards.