Asp.net Documentation
Septimio Sallah
I have a rest api developed using ASP.NET WEB API. I used help pages nuget package in order to create documentation. One problem I encountered is the following. For my model objects, I have xml documentation comments and they become descriptions on the help pages for each member of the model. I want certain part of the description to be on a new line, but everything in the comment comes as one paragraph. I tried to add
in the comments, but didn't help. Does anyone know how to achieve this?
A similar question has been asked here: Web Api Help Page- don't escape html in xml documentation and the accepted answer (which is given by Kiran Challa - one of the ASP.NET Web API team members) describes a work around.
Before selecting or attempting any integration with an API, most developers check out its API documentation. Keeping the API documentation up to date to reflect the software changes is challenging and requires time and effort. In the case of Web APIs, we would like to document the following:
In this article, we will learn about Web API documentation, how we can automatically generate it in ASP .NET Core and how to provide enriched information by offering examples, documentation per different versions, and many more ?.
So, by using OpenAPI in our Web API projects, we can automatically generate our documentation directly from or source code by maintaining the data annotations, XML comments and examples based on our actual data transfer classes. The two main OpenAPI implementations for .NET are Swashbuckle and NSwag. In the examples of the following sections, we will use the Swashbuckle tools.
To provide OpenAPI Documentation, we would start by installing the Swashbuckle.AspNetCore NuGet package. To support API documentation for multiple versions, we need to install the Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer NuGet package.
The AddApiVersioningConfigured extension (can be found in ConfigureApiVersioning.cs) has been updated (in comparison with the one provided in article .NET Nakama (2021, December) to support versioning on our documentation.
Add the UseSwagger() middleware in our Program.cs file to serve the generated OpenAPI definition(s) as JSON files and the UseSwaggerUI() middleware to server the Swagger-UI for all discovered API versions. In the following example, we serve the API documentation only in the development environment. However, we can decide which environments to provide the documentation based on our API audience. Remember that we could only generate the JSON files and serve them (e.g., with Swagger UI) in a separate project.
The structure of the extracted XML documentation is defined in C# by using XML documentation comments. The documentation comments support several XML tags, such as summary, return description, exceptions, list of information, etc. In this article, we will use some of them. For more information about the recommended XML tags for C#, read Wagner B., et al. (2021) article.
To enable the documentation file generation, we should set the GenerateDocumentationFile option to True. Then, the compiler will find all comment fields with XML tags in our source code and create an XML document.
However, when this option is enabled, the compiler will generate CS1591 warnings for any public members in our project without XML documentation comments. We can exclude these warnings by including them in the NoWarn option.
Next, we need to include the XML documentation comments in the OpenAPI definition file. For that purpose, we should use the IncludeXmlComments method in the ConfigureSwaggerSwashbuckle.cs file as shown in the following code.
The Swashbuckle.AspNetCore.Filters NuGet package provides several functionalities that significantly improve our API documentation. For example, we can create valuable request and response examples with valid data, including security requirements, custom request and response headers, etc. In addition, we can manually test our API using these features just by using the Swagger UI without modifying the auto-generated request.
If we use System.ComponentModel.DataAnnotations attributes to validate our DTOs, then the validations are recognized and automatically included in the API documentation. However, we should perform the following steps if we are using FluentValidation for our DTOs.
An Web API documentation provides the necessary information (e.g., endpoints, data contracts, etc.) to describe our Web API to our consumers. However, keeping an up to date Web API documentation is challenging and requires time and effort. Therefore, an easy and automatic process as much as possible would be a great help.
The OpenAPI Specification provides a standardized way of describing Web APIs to allow both humans and computers to generate, discover and understand the API capabilities. In an ASP .NET Core project, we use specific Attributes and XML comments to define all the needed information (e.g., HTTP response codes, information messages, etc.) directly to our source code. Thus, we can provide up-to-date documentation easily as we keep our code up to date.
The essential OpenAPI tools that we would need are a) a tool to generate the OpenAPI definition and b) a tool to generate the API documentation (as a web page, PDF, etc.). This article showed how to use the Swashbuckle tools to create API documentation in an ASP.NET Core project (new or existing) with enriched information.
Before we start with our tutorial, we need to have a working ASP.NET Core application. This documentation is devoted to Hangfire, please, read the official ASP.NET Core Documentation to learn the details on how to create and initialize a new web application: Getting Started and Tutorials.
dotnet try verify dotnet try verify is a compiler for your documentation. With this command, you can make sure that every code snippet will work and is in sync with the backing project. The goal of dotnet try verify is to validate that your documentation works as intended. By running dotnet try verify you will be able to detect markdown and compile errors. For example, if I removed a semicolon from the code snippet above and renamed the region from methods to method, I would get the following errors.
Try .NET source code is now on GitHub! As we are still in the early stages of our development, we are unable to take any feature PRs at the moment but, we do intend to do this in the future. Please feel free to file any bugs reports under our issues. And if you have any feature suggestion, please submit them under our issues using the community suggestions label. Looking forward to seeing all the interactive .NET documentation, and workshop you create.
Welcome to the documentation for YARP! YARP is a library to help create reverse proxy servers that are high-performance, production-ready, and highly customizable. Please provide us your feedback by going to the GitHub repository.
It's no secret that I believe documentation is a crucial element of quality software -- and not just because I've spent most of the last 25 years working on end-user and developer documentation. We've all written code that works perfectly fine for us, because we wrote it, but other users need help knowing what it does and how to put it to work.
It happens all the time and I've seen it over and over. Creating even the most simple documentation -- notes in work tickets, comments in code, a README file -- helps us remember what we created, how it works, and why we coded it that way months later after we've written thousands of lines of completely unrelated code. Or when the colleague who wrote that code leaves the team and now you're responsible for maintaining it. Or someone wants to use the code from your repository and keeps submitting issues asking questions about it...
For .NET Framework development, particularly in C#, XML Documentation Comments are the officially sanctioned way to document your code with the ability to automatically create documentation files from these comments at compile time.
You could create XML documentation comments manually, but you don't have to. Atomineer Pro Documentation for Visual Studio is one of the tools available to parse your code as you write it and automatically create relevant XML comments. It even revises comments on-demand after you make changes to your code. Atomineer also supports Doxygen, Qt and JavaDoc code documentation formats, which I'll get to in a minute.
Sandcastle Help File Builder (SHFB) provides a standalone graphical application, Visual Studio integration package, and MSBuild tasks to generate help files from XML documentation comments. Sandcastle originated in a Microsoft project, but ongoing development is now overseen by Eric Woodruff. This is a free, Microsoft Public License (Ms-PL) with really excellent documentation to get you started building your own docs.
NDoc is an older tool for generating class library documentation from your code assemblies and XML comments. This project hasn't been updated in quite a while. Development continued in a successor project, NDoc3, but that doesn't seem to have been updated since 2013. These projects did, however, provide the basis of some other, newer tools, so I'm including them here for reference purposes.
AutoHelp is a similar documentation generator, providing a very simple engine to read your assemblies and XML documentation to create help files. The key with AutoHelp is the output, which uses ASP.NET MVC 5, ASP.NET WebApi, TypeScript, JQuery and Bootstrap to build your documentation as an attractive, modern web site.
More Code Documentation Tools
There are some other established formats for code documentation, and toolsets that can generate help files from those formats as well as XML comments. Here's a quick overview of those tools.
Doxygen picked up where the NDoc projects left off, and has developed into a highly configurable, flexible code documentation tool for a variety of languages including C/C++, Objective-C, C#, PHP, Java, Python, and others. While primarily developed for Linux and Mac OS X, there are binaries for Windows and the entire project is open sourced under the GNU General Public license. There's extensive documentation for the project.
35fe9a5643