.net core 使用 swagger 生成接口文檔


微軟參考文檔:https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs=visual-studio

在 .net core 中使用 swagger 生成接口文檔跟在 asp.net 中使用方式一樣,但把 swagger 添加到項目中不在生成SwaggerConfig.cs 文件 ,需自己配置。

項目引入Swagger

我這里安裝的是VS2017, 當然 VS Code也是可以的。 Nuget安裝Swagger的命令是:

Install-Package Swashbuckle.AspNetCore -Pre

注意:Nuget包管理添加時一定要注意選擇的時候 選擇 Swashbuckle.AspNetCore 默認的 Swashbuckle 不支持 asp.net core

基於asp.net core 的中間件機制, Swagger也需要加入到中間件服務的列表中, 這樣才可以啟用Swagger。在 Startup.cs 中的 ConfigureServices 跟 Configure 方法添加 Swagger  代碼如下:

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();
            //添加Swagger.
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "DemoAPI", Version = "v1" });
            });
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseMvc();
            //配置Swagger
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "DemoAPI V1");
            });
        }

修改Web API項目首頁重定向

根據需要,找到項目 Properties下的 launchSettings.json 文件,比如修改IIS Express節點下的launchUrl,將其改為下圖中的值,這樣啟動時就重定向到指定的地址

  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },

配置 Swagger UI

安裝好 Swagger 之后,在需要生成 API 文檔的項目當中勾選 XML documentation file. (這個的主要功能是將注釋方法使干什么的 參數的限制顯示出來)

之后我們需要在 StartUp 當中配置 Swagger 相關的設置。

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info() { Title = "測試版本", Version = "v1" });

                options.CustomSchemaIds(type => type.FullName); // 解決相同類名會報錯的問題

                options.IncludeXmlComments(Path.Combine(Directory.GetCurrentDirectory(), "Centa.Data.SwaggerTest.XML")); // 標注要使用的 XML 文檔
            });
        }

編寫完成之后我們運行項目,訪問 swagger 的頁面就會顯示成功了:

 


注意!

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



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