在ASP.NET Core web API中使用Swagger/OpenAPI(介绍)
介绍部分
简介
Swagger(OpenApi)是一个描述REST api的规范,与任何编程语言无关。它允许你在不看源代码的情况下理解REST API的功能以及一些API的细节
官网:Swagger.io
OpenApi和Swagger的区别
- OpenApi是一种规范
- Swagger是使用这种规范的一个工具,产品,比如OpenAPIGenerator和SwaggerUI也是。
OpenAPI规范(openapi.json)
OpenAPI规范一中描述你API功能的一个JSON文档,默认为openapi.json,内容是基于一个XML注释文件(后续提到)和你在Controller和模型类(Dtos or ViewModel)的属性注释,这个openapi.json会用于驱动SwaggerUI界面,所以这OpenApi流程的核心文件。
以下是一个简化版的例子:
{ "openapi": "3.0.1", "info": { "title": "API V1", "version": "v1" }, "paths": { "/api/Todo": { "get": { "tags": [ "Todo" ], "operationId": "ApiTodoGet", "responses": { "200": { "description": "Success", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ToDoItem" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ToDoItem" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ToDoItem" } } } } } } }, "post": { … } }, "/api/Todo/{id}": { "get": { … }, "put": { … }, "delete": { … } } }, "components": { "schemas": { "ToDoItem": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string", "nullable": true }, "isCompleted": { "type": "boolean" } }, "additionalProperties": false } } } }
Swagger UI
Swagger UI基于Web页面,它提供了一些关于api服务的一些信息,这些信息来源于前面的openapi.json。Swashbuckle和NSwag都包含了一个内嵌的Swagger UI,您可以在ASP.NET Core程序中通过注册中间件调用的方式使用它。它长这样(Version 3):
标签:
Swagger(OpenApi)
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 没有源码,如何修改代码逻辑?
· 一个奇形怪状的面试题:Bean中的CHM要不要加volatile?
· [.NET]调用本地 Deepseek 模型
· 一个费力不讨好的项目,让我损失了近一半的绩效!
· .NET Core 托管堆内存泄露/CPU异常的常见思路
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· DeepSeek “源神”启动!「GitHub 热点速览」
· C# 集成 DeepSeek 模型实现 AI 私有化(本地部署与 API 调用教程)
· DeepSeek R1 简明指南:架构、训练、本地部署及硬件要求
· NetPad:一个.NET开源、跨平台的C#编辑器