zoukankan      html  css  js  c++  java
  • .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-x64ChatBotApi.XML</DocumentationFile>
    </PropertyGroup> 
    <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'"> 
        <DocumentationFile>bin$(Configuration)$(TargetFramework)win7-x64ChatBotApi.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 中文文档

  • 相关阅读:
    搭建web攻防环境
    远程控制
    网络攻击
    论文翻译:《PRIMES is in P》——素性测试的确定性多项式时间算法研究
    从Fouier级数到DCT
    同态加密简要概述
    杂谈:探究副词“有点”用于修饰形容词和动词的使用范围
    题解:洛谷P2055/[ZJOI2009] 假期的宿舍(匈牙利算法)
    笔记:二部图最大匹配的匈牙利算法
    杂谈:AI Intro课程作业——卷积神经网络练练手之MNIST数据集
  • 原文地址:https://www.cnblogs.com/shy-huang/p/9102214.html
Copyright © 2011-2022 走看看