.NET Core和Swagger 生成 Api 文檔


測試/生產環境的BUG

這里更新一下在本地調試正常,在INT/PROD上拋錯,錯誤信息為:

*/**/*.xml(Swagger json file) 文件找不到,在startup 里builder 的時候拋出錯誤。

解決方案:

編輯.csproj文件,修改輸出路徑,

<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中。

前言

最近寫了好多Web api, 說太亂了,要整理一下,使用Swagger方式生成對應的api說明文檔。
花了半天的時間,在這里記錄和分享一些過程和遇到的問題。

遇到的主要問題:
1.localhost:9040/swagger/ not found

2.http://localhost:9040/swagger界面可以打開,但是can't read json file.

1.引用

這里引用了三個庫,都是在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"

2.打開startup.cs文件

using Swashbuckle.AspNetCore.Swagger;

在ConfigureServices集合中注入AddSwaggerGen:

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");
        });
}

3.設置XML注釋

在 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)
{
}
        

4.運行結果

1.在瀏覽器中輸入:http://localhost: /swagger/v1/swagger.json

返回Json文檔:

用json viewer打開json文件:

2.在瀏覽器輸入:http://localhost:9040/swagger/

到此說明配置Swagger成功。

詳細的API列表和文檔說明:

5.主要問題的解決辦法

1.RoutePrefix
這是個坑,要好好匹配當前的項目路徑,不然UI打不開

2.SwaggerEndpoint
這是個坑,也是一樣,如果路徑匹配錯誤,UI打開了但是讀取json文檔失敗。

這兩個路徑配置可以多試幾次,我嘗試了幾十次~~

6.可以自定義UI

這個暫時沒有做,今天太晚了,占個位置~

參考文檔

1.Get started with Swashbuckle and ASP.NET Core
2.Swagger .NETCORE can't read json
3.ASP.NET Core 中文文檔


注意!

本站转载的文章为个人学习借鉴使用,本站对版权不负任何法律责任。如果侵犯了您的隐私权益,请联系我们删除。



 
粤ICP备14056181号  © 2014-2021 ITdaan.com