We can't find the internet
Attempting to reconnect
Something went wrong!
Hang in there while we get back on track
OpenAPI & .NET: You're Doing It Wrong - Mark Rendle - NDC London 2023
Explore best practices for using OpenAPI to streamline API documentation and code generation. Learn how to create a single source of truth for your API documentation, generate interactive documenation, and more!
- Don’t maintain separate documents for API documentation and code; instead, keep them in the same repository and use OpenAPI to generate documentation.
- Write a human-focused description of your API, not just rely on machine-generated descriptions.
- Create a single source of truth for your API documentation using OpenAPI.
- Make OpenAPI a part of your codebase by including it in your repository.
- Add YAML comments to describe API endpoints, security, and other details.
- Use OpenAPI to generate documentation and client code in various languages.
- Don’t underestimate the importance of keeping your OpenAPI file up-to-date and accurate.
- Avoid duplicating effort by using OpenAPI to generate documentation and client code.
- Use a tool like Swagger UI to generate interactive documentation for your API.
- Don’t rely on ad-hoc Mardown files or Word documents for API documentation; use OpenAPI instead.
- Keep your OpenAPI file in a version control system and maintain a history of changes.
- Use tools like redoc to generate HTML documentation for your API.
- Don’t bother with outdated and unmaintained OpenAPI versions; use the latest version, which is OpenAPI 3.0.
- Write complex responses using YAML and OpenAPI.
- Don’t hesitate to say “I don’t know” or “I’m not sure” if you’re unsure about something in your API.