When developing a project, it is always necessary to compile the documentation and keep it up-to-date. This can be achieved in several different ways. In general, the automatic documentation capabilities are always used, which allows you to obtain a good quality of documentation with a minimal time cost, which will always correspond to the current version of your API. Currently, a very popular and functional framework for working with the API is Swagger.

Let's create an ASP.NET Core API application. Later, add a default controller ValuesController.

To use Swagger, you must install the following library.

PM > Install-Package Swashbuckle.AspNetCore

Using Swagger In ASP.NET Core
Now, you have to go to the Startup.cs file, go to ConfigureServices, and AddSwaggerGen. The method will look like this.

  1. public void ConfigureServices(IServiceCollection services) {
  2. services.AddMvc();
  3. services.AddSwaggerGen(c => {
  4. c.SwaggerDoc("v1", new Info {
  5. Version = "v1",
  6. Title = "Test API",
  7. Description = "ASP.NET Core Web API"
  8. });
  9. });
  10. }

After that, add the Swagger UI to the Configure method, after which it will look like this.

  1. public void Configure(IApplicationBuilder app, IHostingEnvironment env) {
  2. if (env.IsDevelopment()) {
  3. app.UseDeveloperExceptionPage();
  4. }
  5. app.UseMvc();
  6. app.UseSwagger();
  7. app.UseSwaggerUI(c => {
  8. c.SwaggerEndpoint("/swagger/v1/swagger.json", "Test API V1");
  9. });
  10. }

Using Swagger In ASP.NET Core
If I add a new controller, for example, UsersController, and I add methods to work with the user data, these will automatically begin to appear here.
Using Swagger In ASP.NET Core

You can see which templates are used in the API, which settings are required, and which ones are not. Here too, you can test the work of your methods. To do this, you must select the desired method and click on "Try it out".

Using Swagger In ASP.NET Core

  1. public class UserDto {
  2. [JsonIgnore]
  3. public Guid Id {
  4. get;
  5. set;
  6. }
  7. [Required]
  8. public string FirstName {
  9. get;
  10. set;
  11. }
  12. [Required]
  13. public string LastName {
  14. get;
  15. set;
  16. }
  17. [Required]
  18. [JsonProperty(PropertyName = "mobilePhone")]
  19. public string Phone {
  20. get;
  21. set;
  22. }
  23. public string Email {
  24. get;
  25. set;
  26. }
  27. }

You can see here that you can use various familiar attributes for all, which are well understood and treated in Swagger.

Use in Postman

It is also very convenient to import the JSON, which generates the Swagger in Postman. All you need for a successful import is to insert a link into the JSON file. After that, all the available methods will be available in Postman. The methods for which the description was given will be signed, which further facilitates the use of these methods.

At the moment, Swagger can work with more than 25 programming languages. Its use is, therefore, not limited to .NET Core. It can also be useful in almost any project in which the API is created.