这里更新一下在本地调试正常,在INT/PROD上抛错,错误信息为:html
*/**/*.xml(Swagger json file) 文件找不到,在startup 里builder 的时候抛出错误。git
解决方案:github
编辑.csproj文件,修改输出路径,web
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'"> <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\win7-x64\ChatBotApi.XML</DocumentationFile> </PropertyGroup> <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'"> <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\win7-x64\ChatBotApi.XML</DocumentationFile> </PropertyGroup> <Target Name="PrepublishScript" BeforeTargets="PrepareForPublish"> <ItemGroup> <DocFile Include="bin\$(Platform)\$(Configuration)\$(TargetFramework)\win7-x64\*.xml" /> </ItemGroup> <Copy SourceFiles="@(DocFile)" DestinationFolder="$(PublishDir)" SkipUnchangedFiles="false" /> </Target>
也就是说,让环境本身选择环境变量,保证local/Int/Prod的输出路径都是对的,这样就能够将.xml文件根据环境注入到swagger中。json
最近写了好多Web api, 说太乱了,要整理一下,使用Swagger方式生成对应的api说明文档。
花了半天的时间,在这里记录和分享一些过程和遇到的问题。api
遇到的主要问题:
1.localhost:9040/swagger/ not found
浏览器
2.http://localhost:9040/swagger界面能够打开,可是can't read json file.
app
这里引用了三个库,都是在Nuget上安装:
1.Microsoft.AspNetCore.StaticFiles, Version="2.0.3" , 这个package提供UI显示相关服务
2.Swashbuckle.AspNetCore, Version="2.4.0"
3.Swashbuckle.AspNetCore.SwaggerUi, Version="2.4.0"dom
using Swashbuckle.AspNetCore.Swagger;
在ConfigureServices集合中注入AddSwaggerGen:visual-studio
public void ConfigureServices(IServiceCollection services) { services.AddMvc(); // Enable CORS services.AddCors(); //Inject Swagger services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Info { Title = "MyApi", Version = "v1" }); // Set the comments path for the Swagger JSON and UI. var xmlPath = Path.Combine(AppContext.BaseDirectory, "ChatBotApi.XML"); c.IncludeXmlComments(xmlPath); }); }
在Configure中启用中间件,容许Swagger提供服务生成json文档以及UI:
public void Configure(IApplicationBuilder app, IHostingEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } else { app.UseExceptionHandler("/Home/Error"); } app.UseMvc(routes => { routes.MapRoute( name: "default", template: "{controller}/{action=Index}/{id?}"); }); app.UseStaticFiles(); // Enable middleware to serve generated Swagger as a JSON endpoint. app.UseSwagger(c => { c.RouteTemplate = "swagger/{documentName}/swagger.json"; }); // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), // specifying the Swagger JSON endpoint. app.UseSwaggerUI(c => { //c.RoutePrefix = "swagger/ui"; c.SwaggerEndpoint("v1/swagger.json", "ChatBotApi"); }); }
在 Visual Studio 中右击项目而且选择 Properties 在 Output Settings 区域下面点击 XML Documentation file 。
这时候编译项目,会出现不少warning,提示api没有注释,在每一个Api controller上方,连续输入三个'/',便可将api的对应信息补充完整,要给每一个Api route加上 http的请求方式。
在各个Api里加上注释:
/// <summary> /// Put value by id and value /// </summary> /// <param name="id">id</param> /// <param name="value">value</param> /// PUT api/values/5 [HttpPut("{id}")] public void Put(int id, [FromBody]string value) { }
1.在浏览器中输入:http://localhost:
返回Json文档:
用json viewer打开json文件:
2.在浏览器输入:http://localhost:9040/swagger/
到此说明配置Swagger成功。
详细的API列表和文档说明:
1.RoutePrefix
这是个坑,要好好匹配当前的项目路径,否则UI打不开
2.SwaggerEndpoint
这是个坑,也是同样,若是路径匹配错误,UI打开了可是读取json文档失败。
这两个路径配置能够多试几回,我尝试了几十次~~
这个暂时没有作,今天太晚了,占个位置~
1.Get started with Swashbuckle and ASP.NET Core
2.Swagger .NETCORE can't read json
3.ASP.NET Core 中文文档