前言
回顾上一篇文章《使用 Swagger 做 API 文档 》, 文中介绍了在. net core 3.1 中, 利用 Swagger 轻量级框架, 如何引入程序包, 配置服务, 注册中间件, 一步一步的实现, 最终实现生产自动生产 API 接口说明文档. 文中结尾也留下了一个让大家思考的问题. 在这里, 我们重新回顾一下这几个问题
1. 已经有接口了, 但如何添加注释呢?
2. 作为接口使用者, 我们关心的是接口的返回内容和响应类型, 那我们如何定义描述响应类型呢?
3. 在项目开发中, 使用的实体类, 又如何在 Swagger 中展示呢?
4. 在部署项目, 引用 Swagger 既有文档又不需要额外部署, 但是如何在开发环境中使用, 而在生产环境中禁用呢?
开始
一, 为接口方法添加注释
1 . 按照下图所示 连点三次 / 即可添加文档注释
如下所示
2. 启用 xml 注释
右键 web 项目名称 =>属性 =>生成, 勾选 "输出" 下面的 "xml 文档文件", 系统会默认生成一个, 如下图所示
3. 配置服务
在之前注册的 Swagger 服务代码中, 添加以下几行代码, 引入 xml 文件
- var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);// 获取应用程序所在目录(绝对, 不受工作目录影响, 建议采用此方法获取路径)
- //var basePath = AppContext.BaseDirectory;
- var xmlPath = Path.Combine(basePath, "XUnit.Core.xml");// 这个就是刚刚配置的 xml 文件名
- // c.IncludeXmlComments(xmlPath);// 默认的第二个参数是 false, 对方法的注释
- c.IncludeXmlComments(xmlPath,true); // 这个是 controller 的注释
整体的代码如下:
- public void ConfigureServices(IServiceCollection services)
- {
- services.AddSwaggerGen(c =>
- {
- c.SwaggerDoc("V1", new OpenApiInfo
- {
- Version = "V1", // 版本
- Title = $"XUnit.Core 接口文档 - NetCore3.1", // 标题
- Description = $"XUnit.Core Http API v1", // 描述
- Contact = new OpenApiContact { Name = "艾三元", Email = "", Url = new Uri("http://i3yuan.cnblogs.com") },
- License = new OpenApiLicense { Name = "艾三元许可证", Url = new Uri("http://i3yuan.cnblogs.com") }
- });
- var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);// 获取应用程序所在目录(绝对, 不受工作目录影响, 建议采用此方法获取路径)
- //var basePath = AppContext.BaseDirectory;
- var xmlPath = Path.Combine(basePath, "XUnit.Core.xml");// 这个就是刚刚配置的 xml 文件名
- c.IncludeXmlComments(xmlPath);// 默认的第二个参数是 false, 对方法的注释
- // c.IncludeXmlComments(xmlPath,true); // 这个是 controller 的注释
- });
- services.AddControllers();
- }
4. 重新编译运行
查看效果
注意: 如果需要对控制器进行注释说明如下, 可以将
c.IncludeXmlComments(xmlPath,true); 这个设置为 true, 显示效果如下:
二, 描述响应类型
接口使用者最关心的就是接口的返回内容和相应类型啦. 下面展示一下 201 和 400 一个简单例子:
我们需要在我们的方法上添加:[ProducesResponseType(201)][ProducesResponseType(400)]
然后添加相应的状态说明:<response code="201">返回 value 字符串 </response><response code="400"> 如果 id 为空</response>
最终代码应该是这个样子:
- /// <summary>
- /// values 带 id 参数的 get
- /// </summary>
- /// <param name="id"></param>
- /// <response code="201">返回 value 字符串</response>
- /// <response code="400">如果 id 为空</response>
- /// <returns></returns>
- [HttpGet("{id}")]
- [ProducesResponseType(201)]
- [ProducesResponseType(400)]
- public string Get(int id)
- {
- return "value";
- }
效果如下:
三, 实体类展示添加注释
新建一个 Movie 的实体类, MovieModel
- /// <summary>
- /// 这是电影实体类
- /// </summary>
- public class MovieModel
- {
- /// <summary>
- /// Id
- /// </summary>
- public int Id { get; set; }
- /// <summary>
- /// 影片名称
- /// </summary>
- public string Name { get; set; }
- /// <summary>
- /// 类型
- /// </summary>
- public string Type { get; set; }
- }
在控制器中引入接口方法
- /// <summary>
- /// post 方式提交电影名称
- /// </summary>
- /// <param name="movie"></param>
- [HttpPost]
- public async Task<string> Post(MovieModel movie)
- {
- return movie.Name;
- }
效果如下:
四, 在生产环境中禁用
可以将 Swagger 的 UI 页面配置在 Configure 的开发环境之中
放到 if(env.IsDevelopment())即可.
- public void Configure(IApplicationBuilder App, IWebHostEnvironment env)
- {
- if (env.IsDevelopment())
- {
- App.UseDeveloperExceptionPage();
- #region Swagger 只在开发环节中使用
- App.UseSwagger();
- App.UseSwaggerUI(c => {
- c.SwaggerEndpoint($"/swagger/V1/swagger.json", $"XUnit.Core V1");
- c.RoutePrefix = string.Empty; // 如果是为空 访问路径就为 根域名 / index.html, 注意 localhost:8001/swagger 是访问不到的
- // 路径配置, 设置为空, 表示直接在根域名 (localhost:8001) 访问该文件
- // c.RoutePrefix = "swagger"; // 如果你想换一个路径, 直接写名字即可, 比如直接写 c.RoutePrefix = "swagger"; 则访问路径为 根域名 / swagger/index.HTML
- });
- #endregion
- }
- App.UseRouting();
- App.UseAuthorization();
- App.UseEndpoints(endpoints =>
- {
- endpoints.MapControllers();
- });
- }
五, 隐藏某些接口
如果不想显示某些接口, 直接在 controller 上, 或者 action 上, 增加特性
[ApiExplorerSettings(IgnoreApi = true)]
六, 忽视 Swagger 注释警告
启用 xml 注释后会为未记录的公共类型和成员提供调试信息. 如果出现很多警告信息 例如, 以下消息指示违反警告代码 1591:
原来是 swagger 把一些 action 方法都通过 xml 文件配置了, 如果你不想每一个方法都这么加注释, 可以这么配置, 在当前项目进行配置, 可以忽略警告, 记得在后边加上分号 ;1591
常见错误
在 Swagger 使用的时候报错, 无法看到列表, 这里说下如何调试和主要问题:
1. 找不到文件
请在浏览器 =》 F12 ==》 console 控制台 ==》点击错误信息地址
发现 是 404 , 说明是找不到指定的文件, 可以存在以下情况:
这是因为接口 JSON 文档定义和调用不是一个
1, 定义:
ConfigureServices 方法中的 services.AddSwaggerGen 注册的一个名字 c.SwaggerDoc("v1",
2, 调用:
Configure 方法中的 App.UseSwaggerUI(c => 调用 c.SwaggerEndpoint("/swagger/V1/swagger.JSON;
看看两者是否一致
2. 500 错误无法解析
直接链接 http://localhost:xxxxx/swagger/v1/swagger.JSON, 就能看到错误了
这种可以存在以下情况:
1 . 接口请求的方式不明确: 少了[httpget],[httpPost] 等, 导致无法解析
总结
1. 通过这一篇的整体学习, 我们已经解决了上一篇文章留下的问题, 也知道了怎样更好的使用 Swagger 进行开发接口文档, 更加方便快捷的使用
2. 从上篇的引用配置启动, 到这一篇的升级改造, 让接口文档更加通俗易懂.
3. 关注公众号可以获取资料
下载源码
来源: https://www.cnblogs.com/i3yuan/p/12542291.html