API Documentation in .NET Online Course
This course teaches you how to document ASP.NET Web APIs using Swagger and OpenAPI from scratch. You’ll explore different documentation approaches like XML comments and data annotations, work with tools such as Swagger UI, Swashbuckle, and NSwag, and learn to use analyzers and conventions for efficient, automated documentation. By the end, you’ll be able to create clear, versioned API documentation that makes your web APIs easy to understand and use.
Who should take this course?
This course is designed for .NET developers, software engineers, and technical writers who want to learn best practices for creating clear, accurate, and maintainable API documentation. It’s also valuable for beginners aiming to improve their API communication skills.
What you will learn
- Understand OpenAPI/Swagger and the need for documentation in web API
- Learn the various approaches available to document a web API
- Create an OpenAPI document using Swashbuckle in ASP.NET Web API
- Create an OpenAPI document using NSwag in ASP.NET Web API
- Learn to use Swagger and Swagger UI tools to create a rich API document
- Understand the steps involved in documenting an API with multiple versions
Course Online
Course Introduction
- Welcome to the Course
- About This Course
Getting Started with OpenAPI
- Introduction
- Overview of OpenAPI
- Swagger Versus OpenAPI
- Design-First Versus Code-First
- OpenAPI Implementations for .NET
- Why Document APIs?
- How to Document APIs?
- Overview of Demo Project
Creating OpenAPI Using Swashbuckle
- Introduction
- Overview of Swashbuckle
- Step 1: Install Swashbuckle
- Step 2: Configure Swashbuckle
- A Note about ApiExplorer
- Overview of Generated OpenAPI Spec
- Step 3: Add SwaggerUI
- Summary
Adding Documentation Using Swashbuckle
- Introduction
- Step 4: Add OpenAPI Metadata
- Step 5: Enable Documentation Using XML Comments
- Step 6: Add Documentation Using XML Comments
- Step 7: Add Data Annotations
- Handling Compiler Warnings
- Summary
Creating OpenAPI Using NSwag
- Introduction
- Install NSwag
- Configure NSwag
- Add SwaggerUI
- Summary
Using Web API Analyzers
- Introduction
- What are Web API Analyzers?
- Step 8: Enable Web API Analyzers
- Step 9: Add Annotations as Per Warnings
- Summary
Using Web API Conventions
- Introduction
- What are Web API Conventions?
- Step 10: Applying Web API Conventions
- Step 11: Update Action Names as Per Conventions
- Step 12: Create Custom API Conventions
- Attributes Versus Conventions: Which One to Use?
- Summary
Documenting API Versions
- Introduction
- Step 13: Enable API Versioning
- Need for Handling Version During Documentation
- Step 14: Add Support for Multiple Versions
- Step 15: Add Document for Each Version
- Using Generic Version Handler
- Summary