1、Swagger规范(swagger.json)
Swagger流的核心是Swagger规范-默认情况下,名为swagger.json的文档。它是由Swagger工具链(或其第三方实现)根据您的服务生成的。它描述了您的API的功能以及如何通过HTTP访问它。它驱动Swagger UI,工具链使用它来启用发现和客户端代码生成。这是Swagger规范的示例,为简洁起见,将其简化:
{
"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": {}
}
2、Swagger UI
Swagger UI提供了一个基于Web的UI,它使用生成的Swagger规范提供有关服务的信息。Swashbuckle和NSwag都包含Swagger UI的嵌入式版本,因此可以使用中间件注册调用将其托管在ASP.NET Core应用程序中。Web UI如下所示:
可以从UI中测试控制器中的每种公共操作方法。单击方法名称以展开该部分。添加任何必要的参数,然后单击“Try it out”。
3、Swashbuckle.AspNetCore和NSwag
Swashbuckle.AspNetCore:一个开放源代码项目,用于为ASP.NET Core Web API生成Swagger文档。
NSwag:另一个开源项目,用于生成Swagger文档并将Swagger UI或ReDoc集成到ASP.NET Core Web API中。另外,NSwag提供了为API生成C#和TypeScript客户端代码的方法。
相关文档: