This post was last edited by QWERTYU on 2019-4-12 14:24
introductionAfter using asp.net Core for API development, writing API documentation must be a painful task for programmers, but the documentation must be written, and if there are no specific requirements for the format of the documentation, the final documentation depends entirely on the developer's mood. Or be more detailed, or simpler. So is there a quick and efficient way to build API documentation? The answer is yes, Swagger is one of the most popular REST APIs documentation generation tools!
Why use Swagger as a REST APIs documentation generation tool- Swagger can generate an interactive API console that developers can use to quickly learn and experiment with APIs.
- Swagger can generate client SDK code for implementations on a variety of different platforms.
- Swagger files can be automatically generated from code comments on many different platforms.
- Swagger has a strong community with many strong contributors.
How to use Swagger to generate API documentation in asp.net core?- Swashbuckle.AspNetCore is an open-source project that generates Swagger documentation for ASP.NET Core Web API.
- NSwag is another open-source project for integrating Swagger UI or ReDoc into ASP.NET Core Web APIs. It provides a way to generate C# and TypeScript client code for APIs.
The following is an example of Swashbuckle.AspNetCoreWhat are the components of a Swashbuckle?- Swashbuckle.AspNetCore.Swagger: Exposes the SwaggerDocument object as a Swagger object model and middleware for JSON endpoints.
- Swashbuckle.AspNetCore.SwaggerGen: A Swagger generator that generates SwaggerDocument objects directly from routes, controllers, and models. It is often combined with Swagger endpoint middleware to automatically expose Swagger JSON.
- Swashbuckle.AspNetCore.SwaggerUI: An embedded version of the Swagger UI tool. It interprets Swagger JSON to build customizable, rich experiences that describe the functionality of Web APIs. It includes built-in testing tools for common methods.
How to install Swashbuckle with vs2017?
The first way: install from the Package Manager Console window
- Go to Views > Other Windows > Package Manager Console
- Navigate to the directory that contains the TodoApi.csproj file
- Please execute the following command · Install-Package Swashbuckle.AspNetCore
-
Second way: From the Manage NuGet Packages dialog:- Right-click the project in Solution Explorer > Manage NuGet Packages
- Set Package Source to nuget.org
- Type "Swashbuckle.AspNetCore" in the search box
- Select the Swashbuckle.AspNetCore package from the Browse tab and click Install
-
Add and configure Swagger middlewareIntroduce the namespace first: Add the Swagger generator to the service collection in the Startup.ConfigureServices method: atStartup.Configuremethod, enable middleware to serve the generated JSON document and Swagger UI:
Launch the app and navigate to ithttps://localhost:<port>/swagger/v1/swagger.json。 The resulting documentation describing the endpoint is displayed in JSON format as follows.
Availablehttps://localhost:<port>/swaggerLocate the Swagger UI. Browse the API documentation through the Swagger UI as shown below.
To apply the root (http://localhost:<port>/) to provide the Swagger UI, please put the RoutePrefixThe property is set to an empty string:
Advanced Usage of Swagger (Customization and Extensions)Use Swagger to add explanatory information to API documentationThe following configuration operations are performed in the AddSwaggerGen method, which adds information such as author, license, and description information: The information of the wagger UI display version is shown in the following figure: Add comments to interface methodsLet's click on the API first, expand as shown in the figure below, can there be no comments, how to add comments? Add document comments with three/as shown in the image below, as shown below Then run the project and go back to the swaggerUI to see if the comment appears Still didn't appear, don't worry, look down! Enable XML annotationsYou can enable XML annotations using the following methods: - Right-click the project in Solution Explorer and select Properties
- Look at the XML Document File box under the Output section of the Build tab
-
Enabling XML annotations provides debugging information for undocumented common types and members. If a lot of warning messages appear, for example, the following message indicates a violation of warning code 1591:
What if you have OCD and want to cancel the warning? You can cancel as shown in the image below
Note the path of the xml document file generated above,
Note: 1. For Linux or non-Windows operating systems, file names and paths are case-sensitive. For example, a "SwaggerDemo.xml" file works on Windows, but not on CentOS. 2. To obtain the application path, it is recommended to use AppContext.BaseDirectory to obtain it Rebuild and run the project to see if the comments appear From the above operation, it can be summarized that the Swagger UI displays the <summary> internal text of the elements of the above comment code as API large comments! Of course, you can also add the remarks element to the Get how-to documentation. It can complement <summary> the information specified in the element and provide a more reliable Swagger UI. <remarks> Element content can contain text, JSON, or XML. The code is as follows: Test the api interface using SwaggerUILet's debug the interface through SwaggerUI through a small example
- Click on an API interface that needs to be tested, and then click the "Try it out" button on the left and right of Parameters
- Enter a parameter in the parameter text box that appears, as shown in the following image, enter parameter 2
- Click the Execute button, and the formatted Response shown below will appear, as shown in the figure below
Well, that's it for today's tutorial on using Swagger to generate api documentation in ASP.NET Core WebApi. I hope it will be helpful for you to learn how to use Swagger to generate API documentation in ASP.NET Core! summaryThis article starts with the pain point of writing API documentation by hand, and then leads to Swagger, a tool that automatically generates API documentation! Then, through easy-to-understand text and pictures, we will demonstrate how to use SwaggerUI to generate API documentation in a ASP.NET Core WebApi. Finally, I will introduce some advanced uses of Swagger in ASP.NET Core! I hope it helps you use Swagger in ASP.NET Core!
| 
Posted on 4/12/2019 2:14:46 PM
|
|
|
|
