{"id":29039,"date":"2019-02-19T00:00:00","date_gmt":"2019-02-18T23:00:00","guid":{"rendered":"https:\/\/blexin.com\/documentare-le-api-con-swagger\/"},"modified":"2021-05-20T19:24:05","modified_gmt":"2021-05-20T17:24:05","slug":"documenting-api-with-swagger","status":"publish","type":"post","link":"https:\/\/blexin.com\/en\/blog-en\/documenting-api-with-swagger\/","title":{"rendered":"Documenting API with Swagger"},"content":{"rendered":"\n
\"\"<\/figure>\n\n\n\n

I recently worked on the backend of an application, for one of our clients. Some tasks<\/em> concerned the introduction of new API to be noticed with Swagger<\/strong> and, specifically, one of these requires to habilitate Swagger only for the debug environment<\/em> and to disable it for the production environment<\/em>.<\/p>\n\n\n\n

But what is Swagger? It is a tools set, that accompanies the specification OpenApi<\/a><\/strong> (OAS<\/strong>), namely the standard for API Rest description, to create and document these API. The OAS<\/strong> standard is independent from the programming language, and it has been designed to be comprehensible both for people and for computers. The goal is to make understandable what is made available from a services, with no need to access to source codes or to an additional documentation.<\/p>\n\n\n\n

In a .Net project it\u2019s possible to integrate Swagger installing, via Nuget, the Open Source package Swashbuckle<\/strong>. Once installed, we will find in the folder App_start<\/em> the file SwaggerConfig.cs<\/em>.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

This file contains many useful comments for the configuration of Swagger<\/strong> for our application. In particular, we can indicate a XML<\/em> file, where will be saved the comments in which we can save our API.<\/p>\n\n\n

\nc.IncludeXmlComments(GetXmlCommentsPath());\n<\/pre><\/div>\n\n\n
To avoid mistakes, we need to go in project properties, tab Build<\/em>, section Output<\/em>, flag the option “XML documentation file”, indicate the destination file XML<\/em>.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
As soon as we finish this configuration, it\u2019s possible to notice the API with following tags<\/em> :<\/p>\n\n\n\n