我们为什么需要文档
好的文档能够让前后端开发沟通更轻松
Swagger ui 文档的优点
可在线测试的,方便前后端调试
使用步骤
- 新建WebApi 项目
- Nuget 引入相应的类库 Install-Package Swashbuckle (swaggerui 2.0)
- 引入之后,会在App_Start 目录生成 SwaggerConfig.cs 文件
- 修改 SwaggerConfig.cs 文件 c.IncludeXmlComments 函数,引入需要包含的 xml 文件(c# summary 注释会自动生成xml文件)
- 多个项目需要引入多个xml文件
- 修改每个项目对应的属性-》build-》输出-》勾选 xml文档文件
- 启动项目 访问 xxx:xx/swagger 就能看到自动生成文档了,对应json,可以查看swaggerui 头部输入框里的 连接
常见错误
1 直接访问加载不出来文档,如果使用json.net的序列化,需要设置 NullHanding 为 ignore
settings.NullValueHandling = NullValueHandling.Ignore;
2 如果生成的复杂参数没有正确解析为对象,请检查是否设置了 json.net 驼峰 返回