5.1 KiB
| title | author | description | ms.author | ms.custom | ms.date | uid |
|---|---|---|---|---|---|---|
| ASP.NET Core Web API help pages with Swagger / Open API | rsuter | This tutorial provides a walkthrough of adding Swagger to generate documentation and help pages for a Web API app. | scaddie | mvc | 03/09/2018 | tutorials/web-api-help-pages-using-swagger |
ASP.NET Core Web API help pages with Swagger / Open API
By Christoph Nienaber and Rico Suter
When consuming a Web API, understanding its various methods can be challenging for a developer. Swagger, also known as Open API, solves the problem of generating useful documentation and help pages for Web APIs. It provides benefits such as interactive documentation, client SDK generation, and API discoverability.
In this article, the Swashbuckle.AspNetCore and NSwag .NET Swagger implementations are showcased:
-
Swashbuckle.AspNetCore is an open source project for generating Swagger documents for ASP.NET Core Web APIs.
-
NSwag is another open source project for integrating Swagger UI or ReDoc into ASP.NET Core Web APIs. It offers approaches to generate C# and TypeScript client code for your API.
What is Swagger / Open API?
Swagger is a language-agnostic specification for describing REST APIs. The Swagger project was donated to the OpenAPI Initiative, where it's now referred to as Open API. Both names are used interchangeably; however, Open API is preferred. It allows both computers and humans to understand the capabilities of a service without any direct access to the implementation (source code, network access, documentation). One goal is to minimize the amount of work needed to connect disassociated services. Another goal is to reduce the amount of time needed to accurately document a service.
Swagger specification (swagger.json)
The core to the Swagger flow is the Swagger specification—by default, a document named swagger.json. It's generated by the Swagger tool chain (or third-party implementations of it) based on your service. It describes the capabilities of your API and how to access it with HTTP. It drives the Swagger UI and is used by the tool chain to enable discovery and client code generation. Here's an example of a Swagger specification, reduced for brevity:
{
"swagger": "2.0",
"info": {
"version": "v1",
"title": "API V1"
},
"basePath": "/",
"paths": {
"/api/Todo": {
"get": {
"tags": [
"Todo"
],
"operationId": "ApiTodoGet",
"consumes": [],
"produces": [
"text/plain",
"application/json",
"text/json"
],
"responses": {
"200": {
"description": "Success",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/TodoItem"
}
}
}
}
},
"post": {
...
}
},
"/api/Todo/{id}": {
"get": {
...
},
"put": {
...
},
"delete": {
...
},
"definitions": {
"TodoItem": {
"type": "object",
"properties": {
"id": {
"format": "int64",
"type": "integer"
},
"name": {
"type": "string"
},
"isComplete": {
"default": false,
"type": "boolean"
}
}
}
},
"securityDefinitions": {}
}
Swagger UI
Swagger UI offers a web-based UI that provides information about the service, using the generated Swagger specification. Both Swashbuckle and NSwag include an embedded version of Swagger UI, so that it can be hosted in your ASP.NET Core app using a middleware registration call. The web UI looks like this:
Each public action method in your controllers can be tested from the UI. Click a method name to expand the section. Add any necessary parameters, and click Try it out!.
[!NOTE] The Swagger UI version used for the screenshots is version 2. For a version 3 example, see Petstore example.