告别手写,在Asp.Net Core中轻松集成swagger和redoc接口文档

创业资讯 阅读(993)
sunbet手机中文版

Swagger使我们成为api开发中的常用技术,它解决了web api文档生成的问题。它具有许多优点,例如交互式文档,客户端SDK生成和api可发现性。由于作者正在开发.net核心方向,我们来谈谈在.net核心web api项目中集成swagger或redoc。

b58daaeae52b44de90712c7d1a5443fc

本文重点介绍如何使用NSwag.NET将swagger集成到项目中,包括swagger和redoc。 Redoc也可以集成到项目中。它可以说是对ui更加昂首阔步或更友好的替代品。有搜索功能!当然,有些朋友可能会使用Swashbuckle.AspNetCore来集成招摇,其实也没关系。

开源地址:

我使用的是VS2019版本,VS2017类似

选择您要创建的项目

在这里我们选择asp.net核心Web应用程序,然后下一步

c6800e9b84db4c9a8425f2ad42376aa9

项目命名

VS2019和VS2017略有不同

b963157a686745a4a417468e989f69c8

选择类型

这里我们选择API,然后我们为.net核心版本选择2.2,你也可以选择3.0,但它仍然是预览版,你可以提前学习

e9ab32bdcec34ce9977edbb5f1f46ca9

创建一个简单的项目

这里的控制器并不急于删除,我们用它来演示生成的文件

7474f113c8fd47e48ea85802976a0464

右键单击该项目以打开Nuget Pack Management95a73b98ba444af49e0ae7f114cd8d1a

搜索NSwag.AspNetCore并安装

NSwag.AspNetCore包括生成和提供Swagger规范,SwaggerUI(V2和V3版本)和Redoc UI

58e66e19316c4fab8763e2a22e8a035a

注册NSwag中间件

asp.net核心中的中间件已被大量使用。要使用NSwag,我们需要在Startup文件中注册中间件,并在Startup.ConfigureServices方法中注册所需的Swagger服务

Public void ConfigureServices(IServiceCollection services)

{

services.AddMvc()SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

services.AddSwaggerDocument();

}

使

在Startup.Configure方法中,启用中间件以提供生成的Swagger规范和Swagger UI

Public void Configure(IApplicationBuilder app,IHostingEnvironment env)

{

app.UseStaticFiles();

//注册Swagger生成器和Swagger UI中间件

app.UseOpenApi();

app.UseSwaggerUi3();

app.UseMvc();

}

启动项目

首先,我们需要删除启动配置文件中的https

07c791c8c2fa4b8fb47acefbd8c2db0c

打开浏览器

然后是熟悉的文档样式

16b96421088c42b1ae18d497f2a2d6ab

自定义一些配置

在Startup.ConfigureServices方法中,传递给AddSwaggerDocument方法的配置操作添加了诸如作者,许可证和描述之类的信息:

services.AddSwaggerDocument(config=>

{

config.PostProcess=document=>

{

document.Info.Version='v1';

document.Info.Title='API';

document.Info.Description='经过测试的文档';

document.Info.TermsOfService='无';

document.Info.Contact=new NSwag.OpenApiContact

{

名称='测试',

Email=string.Empty,

Url=''

};

document.Info.License=new NSwag.OpenApiLicense

{

Name='在LICX下使用',

Url=''

};

};

});

6ad1f1bfd0d74610928e02e4938b9117

以上是Swagger的一些配置,基本上可以满足日常开发需求,但在实际开发过程中,随着API的增加,搜索是完全错误的,那么就没有办法搜索,答案是肯定的,那就是Redoc 。

集成redoc

Redoc实际上是一个独立的存在,但为了方便我们可以集成到项目中,首先修改静态文件的配置,然后创建一个新的wwwroot文件夹,添加index.html文件,内容如下

app.UseStaticFiles(new StaticFileOptions

{

FileProvider=new PhysicalFileProvider(

Path.Combine(Directory.GetCurrentDirectory(),'wwwroot')),

RequestPath='/wwwroot',

});

ReDoc

体{

保证金: 0;

填充: 0;

}

用搜索功能打开浏览器,其实redoc还有很多其他功能,它们不会一一介绍

b6eb0206b5624f7cb6a8ebaed33ed4fd

以上是在Asp.net核心项目中继承Swagger攻击Redoc文档的简单方法,该项目基本满足了我们的日常开发需求。如果需要小伙伴,我希望能帮到你!

PS:可以通过swagger与上一篇文章中介绍的YAPI接口管理平台无缝连接,你可以看看吧!