• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    公众号

asp.netcoreswagger使用及注意事项

原作者: [db:作者] 来自: [db:来源] 收藏 邀请

 

  Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。是一款RESTFUL接口的文档在线自动生成+功能测试软件。主要目的是构建标准的、稳定的、可重用的、交互式的API以及简单方便的功能测试。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

 作用:

    1. 根据基于规范的标准设计和建模API

    2. 几乎可以用任何语言为您的API构建稳定,可重用的代码

 3. 使用交互式API文档改善开发人员体验

 4. 对您的API执行简单的功能测试,而无需开销

 5. 在您的API架构中设置和实施API样式指南

1.新建asp.net core项目

2.nuget上安装Swashbuckle.AspNetCore

Swashbuckle有三个主要组件:

  • Swashbuckle.AspNetCore.Swagger:一个Swagger对象模型和中间件,用于将SwaggerDocument对象公开为JSON端点。

  • Swashbuckle.AspNetCore.SwaggerGen:一个Swagger生成器,可SwaggerDocument直接从路由,控制器和模型构建对象。它通常与Swagger端点中间件结合使用,以自动显示Swagger JSON。

  • Swashbuckle.AspNetCore.SwaggerUI:Swagger UI工具的嵌入式版本。它解释了Swagger JSON,以便为描述Web API功能构建丰富,可定制的体验。它包括用于公共方法的内置测试工具。

3.在Startup的 ConfigureServices配置服务中添加中间件

public void ConfigureServices(IServiceCollection services)
        {
            services.Configure<CookiePolicyOptions>(options =>
            {
                // This lambda determines whether user consent for non-essential cookies is needed for a given request.
                options.CheckConsentNeeded = context => true;
                options.MinimumSameSitePolicy = SameSiteMode.None;
            });
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
            });
        }

4.在Startup的 Configure配置服务中启用中间件

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler("/Home/Error");
                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
                app.UseHsts();
            }

            app.UseHttpsRedirection();
            app.UseStaticFiles();
            app.UseCookiePolicy();

            app.UseMvc(routes =>
            {
                routes.MapRoute(
                    name: "default",
                    template: "{controller=Home}/{action=Index}/{id?}");
            });

            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.InjectJavascript("");
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
            });
        }

5.启动程序,然后键入url  swagger/index.html或者swagger

 

 

6.修改Web API项目首页重定向

在 Properties >> launchSettings.json文件中更改默认配置 >> 启用 "launchUrl": "swagger"配置

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:49833",
      "sslPort": 44387
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "SwaggerTest": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "http://localhost:49833/swagger",
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

 

7.为控制器中每个方法添加注释启用XML注释为未记录的公共类型和成员提供调试信息     项目 >> 属性 >> 生成

 

修改Startup的 ConfigureServices配置服务

public void ConfigureServices(IServiceCollection services)
        {
            services.Configure<CookiePolicyOptions>(options =>
            {
                // This lambda determines whether user consent for non-essential cookies is needed for a given request.
                options.CheckConsentNeeded = context => true;
                options.MinimumSameSitePolicy = SameSiteMode.None;
            });
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
                //添加xml文件
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                c.IncludeXmlComments(xmlPath);
            });
        }

 

 

 8.添加控制器,启动  创建成功

 

二 、注意事项

1.启动后出现 No operations defined in spec! 问题

在查看/swagger/v1/swagger.json文件后发现是没有配置parh

打开后内容是:

{"swagger":"2.0","info":{"version":"v1","title":"My API"},"paths":{},"definitions":{}}

 

 

解决:该项目中未添加API控制器,注意必须是API控制器,并且需要在处理方法上添加HTTP标记

/// <summary>
        /// Delete
        /// </summary>
        /// <param name="ids">删除id列表</param>
        /// <returns>被成功删除id列表</returns>
        [HttpDelete]
        public ActionResult<IEnumerable<string>> Delete(params string[] ids)
        {
            if (ids == null)
                return NoContent();
            return ids;
        }

        /// <summary>
        /// Update
        /// </summary>
        /// <param name="id">Update id</param>
        /// <returns></returns>
        [HttpPut]
        public IActionResult Update(string id)
        {
            return Content("Update id:" + id);
        }

        /// <summary>
        /// Add
        /// </summary>
        /// <param name="param">Add ids</param>
        /// <returns></returns>
        [HttpPost]
        public IActionResult Add(params string[] param)
        {
            return Content(string.Join(",", param));
        }

2.启动后出现  Failed to load API definition.  错误 

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;

namespace SwaggerTest.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class DefaultController : ControllerBase
    {
        /// <summary>
        /// Delete
        /// </summary>
        /// <param name="ids">删除id列表</param>
        /// <returns>被成功删除id列表</returns>
        //[HttpDelete]
        public ActionResult<IEnumerable<string>> Delete(params string[] ids)
        {
            if (ids == null)
                return NoContent();
            return ids;
        }

        /// <summary>
        /// Update
        /// </summary>
        /// <param name="id">Update id</param>
        /// <returns></returns>
        [HttpPut]
        public IActionResult Update(string id)
        {
            return Content("Update id:" + id);
        }

        /// <summary>
        /// Add
        /// </summary>
        /// <param name="param">Add ids</param>
        /// <returns></returns>
        [HttpPost]
        public IActionResult Add(params string[] param)
        {
            return Content(string.Join(",", param));
        }
    }
}

 

原因:控制器中出现未被HTTP标记的方法

解决方案:删除该方法或者添加相应的HTTP标记

 

 

官网文档:https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-2.2&tabs=netcore-cli#add-and-configure-swagger-middleware

更多请参考swagger官网:https://swagger.io/

 


鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
上一篇:
asp.netmvc+EF递归生成树结构返回json发布时间:2022-07-10
下一篇:
asp.netcore系列77webapi响应压缩发布时间:2022-07-10
热门推荐
热门话题
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap