ASP.NET Web API Help Pages using Swagger

标签：

Understanding the various methods of an API can be a challenge for a developer when building a consuming application.

Generating good documentation and help pages as a part of your Web API using Swagger with the .NET Core implementation Swashbuckle is as easy as adding a couple of NuGet packages and modifying the Startup.cs.

This tutorial builds on the sample on Building Your First Web API with ASP.NET Core MVC and Visual Studio. If you‘d like to follow along, download the sample at https://github.com/aspnet/Docs/tree/master/aspnetcore/tutorials/first-web-api/sample.

Getting Started

There are two core components to Swashbuckle

Swashbuckle.SwaggerGen : provides the functionality to generate JSON Swagger documents that describe the objects, methods, return types, etc.

Swashbuckle.SwaggerUI : an embedded version of the Swagger UI tool which uses the above documents for a rich customizable experience for describing the Web API functionality and includes built in test harness capabilities for the public methods.

NuGet Packages

You can add Swashbuckle with any of the following approaches:

From the Package Manager Console:

Copy

bash

Install-Package Swashbuckle -Pre

In Visual Studio:

Right click your project in Solution Explorer > Manage NuGet Packages

Enter Swashbuckle in the search box

Check "Include prerelease"

Set the Package source to nuget.org

Tap the Swashbuckle package and then tap Install

Add and configure Swagger to the middleware

Add SwaggerGen to the services collection in the Configure method, and in the ConfigureServices method, enable the middleware for serving generated JSON document and the SwaggerUI.

Copy

C#

public void ConfigureServices(IServiceCollection services) { // Add framework services. services.AddMvc(); services.AddLogging(); // Add our repository type services.AddSingleton<ITodoRepository, TodoRepository>(); // Inject an implementation of ISwaggerProvider with defaulted settings applied services.AddSwaggerGen(); } // This method gets called by the runtime. Use this method to configure the HTTP request pipeline. public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory) { app.UseMvcWithDefaultRoute(); // Enable middleware to serve generated Swagger as a JSON endpoint app.UseSwagger(); // Enable middleware to serve swagger-ui assets (HTML, JS, CSS etc.) app.UseSwaggerUi(); }

In Visual Studio, press ^F5 to launch the app and navigate to :<random_port>/swagger/v1/swagger.json to see the document generated that describes the endpoints.

Note

Microsoft Edge, Google Chrome and Firefox display JSON documents natively. There are extensions for Chrome that will format the document for easier reading. Example below reduced for brevity.

Copy

JavaScript

{ "swagger": "2.0", "info": { "version": "v1", "title": "API V1" }, "basePath": "http://www.mamicode.com/", "paths": { "/api/Todo": { "get": { "tags": [ "Todo" ], "operationId": "ApiTodoGet", "consumes": [], "produces": [ "text/plain", "application/json", "text/json" ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/TodoItem" } } } }, "deprecated": false }, "post": { ... } }, "/api/Todo/{id}": { "get": { ... }, "put": { ... }, "delete": { ... }, "definitions": { "TodoItem": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "isComplete": { "type": "boolean" } } } }, "securityDefinitions": {} }

This document is used to drive the Swagger UI which can be viewed by navigating to :<random_port>/swagger/ui

Each of the methods in the ToDo controller can be tested from the UI. Tap a method to expand the section, add any necessary parameters and tap "Try it out!".

Customization & Extensibility

Swagger is not only a simple way to represent the API, but has options for documenting the object model, as well as customizing the interactive UI to match your look and feel or design language.

API Info and Description

The ConfigureSwaggerGen method can be used to add information such as the author, license, description.

Copy