{"id":1590,"date":"2020-10-25T08:47:38","date_gmt":"2020-10-25T08:47:38","guid":{"rendered":"https:\/\/serkanseker.com\/?p=1590"},"modified":"2020-12-08T15:35:20","modified_gmt":"2020-12-08T15:35:20","slug":"swagger-api-documentation-tool","status":"publish","type":"post","link":"https:\/\/serkanseker.com\/tr\/swagger-api-documentation-tool\/","title":{"rendered":"Swagger API Documentation Tool"},"content":{"rendered":"\n

Do you need documentation showing how developers and customers will use web API projects? And you think how to document your API. Don’t worry, there are several tools that do this. The most preferred of these is the Swagger Documentation Tool. At the end of this post, you will be able to document your API and present it to the end user.<\/p>\n\n\n\n

In this post, I will document the web API project we created earlier. If you do not have a web API project, read the Create And Consume ASP.NET Core Web API<\/a> to create a Web API. <\/p>\n\n\n\n

Table Of Contents<\/p>

  1. What is Swagger?<\/a><\/strong>

    <\/p> <\/li>

  2. Download NSwag.AspNetCore NuGet Package<\/a><\/strong>

    <\/p> <\/li>

  3. Configure Swagger Middleware<\/a><\/strong>

    <\/p> <\/li>

  4. Test Methods in Swagger<\/a><\/strong>

    <\/p> <\/li>

  5. Add Description to Methods<\/a><\/strong>

    <\/p> <\/li>

  6. API Info And Description<\/a><\/strong>

    <\/p> <\/li>

  7. Conclusion<\/a><\/strong>

    <\/p> <\/li><\/ol><\/div>\n\n\n\n

    What is Swagger?<\/h2>\n\n\n\n

    Developed by SmartBear to better implement and visualize APIs. They define themselves as follows:<\/p>\n\n\n\n

    \n
    <\/div>\n<\/div>\n\n\n\n

    Swagger<\/strong> is a set of rules (in other words, a specification) for a format describing REST APIs<\/strong>. As a result, it can be used to share documentation among product managers, testers and developers, but can also be used by various tools<\/strong> to automate API<\/strong>-related processes.<\/p><\/blockquote>\n\n\n\n

    Download NSwag.AspNetCore NuGet Package<\/h2>\n\n\n\n

    Right-click the existing API project and click the Manage NuGet package option. For Core based projects, search and download the NSwag.AspNetCore<\/a> plugin here. Or you can install it by typing the following line into Package Manager Console.<\/p>\n\n\n\n

    Install-Package NSwag.AspNetCore -Version 13.8.2<\/code><\/pre>\n\n\n\n
    \"Download
    Download NSwag.AspNetCore NuGet Package<\/figcaption><\/figure>\n\n\n\n
    Configure Swagger Middleware<\/h2>\n\n\n\n
    After loading the plugin to the project, we must declare the Swagger document in the ConfigureServices and Configure methods in the Startup.cs class.<\/p>\n\n\n\n
    Add the following line to the ConfigureServices method of the Startup.cs class. This code registers the plugin’s services.<\/p>\n\n\n\n
    services.AddSwaggerDocument();<\/code><\/pre>\n\n\n\n
    And, add the following lines to enable middleware to provide Swagger features and user interface in Configure method.<\/p>\n\n\n\n
    app.UseOpenApi();\napp.UseSwaggerUi3();<\/code><\/pre>\n\n\n\n
    Run the application and go to http:\/\/localhost:<port>\/swagger<\/strong> to view the interface. Also, go to http:\/\/localhost:<port>\/swagger\/v1\/swagger.json<\/strong> to view properties.<\/p>\n\n\n\n
    \"Launch
    Launch Swagger<\/figcaption><\/figure>\n\n\n\n
    Test Methods in Swagger<\/h2>\n\n\n\n
    Let me try the Users Controllers’ GET method as an example. Click on the try it out button and enter the id parameter. Then click on execute.<\/p>\n\n\n\n
    \"Test
    Swagger Test Methods<\/figcaption><\/figure>\n\n\n\n
    This is our result. You can also download the response body as JSON file.<\/p>\n\n\n\n
    Add Description to Methods<\/h2>\n\n\n\n
    We can write a summary on the methods in the Controllers classes, explaining which methods will be used for what, which parameters will be taken to the user. Swagger will add these summaries as comments next to the methods. Let’s do an example.<\/p>\n\n\n\n
    First, write the required explanation in the summary tag above the method as below. Tip<\/strong>: Typing \/\/\/ automatically opens the summary tab.<\/p>\n\n\n\n
    \/\/\/ <summary>\n\/\/\/ Get All Users from database.\n\/\/\/ <\/summary>\n\/\/\/ <returns><\/returns>\n\/\/ GET: api\/Users\n[HttpGet]\npublic async Task<ActionResult<IEnumerable<Users>>> GetUsers()\n{   \n    return await _context.Users.ToListAsync();\n}<\/code><\/pre>\n\n\n\n
    Then right click on the project and open the properties window. Then, activate the XML documentation file<\/strong> option from the Build tab.<\/p>\n\n\n\n
    \"XML
    XML documentation file<\/strong><\/figcaption><\/figure>\n\n\n\n
    Here now run the application.<\/p>\n\n\n\n
    \"Add
    Add Description to Methods<\/figcaption><\/figure>\n\n\n\n
    API Info And Description<\/h2>\n\n\n\n
    To add information such as author, license, version to the document, you can add the required information to the AddSwaggerDocument<\/strong> method in the Startup.ConfigureServices<\/strong> method.<\/p>\n\n\n\n
                services.AddSwaggerDocument(config =>\n            {\n                config.PostProcess = (doc =>\n                {\n                    doc.Info.Version = "v2";\n                    doc.Info.Title = "Palette Core API";\n                    doc.Info.Contact = new NSwag.OpenApiContact()\n                    {\n                        Name = "Serkan",\n                        Url = "https:\/\/serkanseker.com\/",\n                        Email = "info@codesitory.com",\n                    };\n                });\n            });<\/code><\/pre>\n\n\n\n
    Here now run the application.<\/p>\n\n\n\n
    \"Swagger
    Swagger API Info And Description<\/figcaption><\/figure>\n\n\n\n
     Conclusion<\/h2>\n\n\n\n
    Documentation preparation process for Web API projects can be done easily with the help of Swagger. In addition, the response bodies of the tested queries can be downloaded in JSON format. That’s all from this post.<\/p>\n\n\n\n
    Related Links<\/h2>\n\n\n\n