使用Spring REST API设置Swagger 2
最后修改:2021年1月9日
1.概述
如今，前端和后端组件通常分开Web应用程序。通常，我们将API暴露为前端组件或第三方应用集成的后端组件。
在这样的场景中，必须为后端API具有适当的规范。与此同时，API文档应该是信息性的，可读的，易于遵循的。
此外，参考文档应该同时描述API中的每一个变化。手动完成这是一个繁琐的运动，因此过程的自动化是不可避免的。
在本教程中，我们会看看Swigger 2用于春眠Web服务，使用Swagger 2规范的Springfox实现。
如果你不熟悉招摇，请访问它的网页在继续本教程之前了解更多信息。
进一步阅读：
2.目标项目
我们将使用的REST服务的创建不在本文的讨论范围之内。如果您已经有了一个合适的项目，那么就使用它。如果没有，这些链接是一个很好的开始:
3.添加Maven依赖项
如上所述，我们将使用Springfox实现摇摆规范。可以找到最新版本在Maven Central.。
要将其添加到我们的Maven项目中，我们需要一个依赖pom.xml文件：
<依赖> io.springfox Springfox-Swagger2 2.9.2 3.1。春天启动依赖项
对于基于Spring启动的项目，它足以添加一个单一Springfox-Boot-Starter依赖性:
<依赖项> io.springfox Springfox-Boot-Starter 3.0.0 我们可以添加我们需要的任何其他启动器，使用Spring Boot父级管理的版本:
<依赖项> org.springframework.boot Spring-Boot-Starter-Parent 2.4.0 4.将Swagger 2集成到项目中
4.1。Java配置
Swagger的配置主要围绕摘要豆角，扁豆：
@configuration公共类springfoxconfig {@bean public docket api（）{return new docket（documentationtype.swagger_2）.select（）.apis（requestHandlerselectors.any（））.paths（pathselectors.any（））.build（）;}}在定义这一点后摘要豆，它选择（）方法返回一个实例ApiSelectorBuilder，它提供了一种控制蜂拥而至暴露的端点的方法。
我们可以配置选择谓词RequestHandler.借助RequestHandLerselectors.和PathSelectors。使用任何（）对于这两者都将通过播放器提供整个API的文档。
4.2。无弹簧启动配置
在普通Spring项目中，我们需要明确启用Swagger 2。要做到这一点,我们必须使用@ EnableWgger2WebMVC.在我们的配置类上:
@configuration @ emablywagger2webmvc公共类springfoxconfig {}此外，如果没有春天的启动，我们没有奢侈的自动配置我们的资源处理程序。
Swagger UI添加了一组资源，我们必须将其配置为扩展类的一部分WebMvcConfigurerAdapter并被注释@bablewebmvc：
@override public void addresourceHandlers（ResourceHandlerRegistry注册表）{Registry.AddresourceHandler（“Swagger-UI.HTML”）.Addresourcelocations（“类路径：/ meta-Inf / Resources /”）;Registry.AddresourceHandler（“/ webjars / **”）.addresourcelocations（“类路径：/ meta-inf / companess / webjars /”）;}4.3。确认
要验证Springfox是否正常工作，我们可以在我们的浏览器中访问此URL：
http：// localhost：8080 / spring-security-rest / api / v2 / api-docs
结果是具有大量密钥值对的JSON响应，这不是非常人性的可读性。幸运的是，沃克提供了招摇UI.以此目的。
5.招摇UI.
Swagger UI是一个内置解决方案，使用户与Swagger生成的API文档更容易的交互。
5.1。启用Springfox的播放UI
要使用Swagger UI，我们需要添加额外的Maven依赖项：
<依赖> < groupId > io。springfox 2.9.2 现在我们可以通过访问来测试它的浏览器：
http：// localhost：8080 /您的app-root / swagger-ui /
顺便说一下，在我们的例子中，确切的URL是:
http：// localhost：8080 / spring-security-rest / api / swagger-ui /
结果应该看起来像这样：
5.2。探索摇摆文献
在Swagger的回答中是一个列出所有控制器在我们的申请中定义。单击其中任何一个都将列出有效的HTTP方法（删除,得到,头,选项,补丁,帖子,放）。
展开每个方法会提供额外的有用数据，如响应状态、内容类型和参数列表。也可以使用UI尝试每种方法。
Swagger与我们的代码基础同步的能力至关重要。要演示这一点，我们可以为我们的应用程序添加新控制器：
@RestController公共类CustomController {@RequestMapping（value =“/自定义”，方法= requestmethod.post）公共字符串自定义（）{return“自定义”;}}现在，如果我们刷新摇摆文档，我们会看到custom-controller在控制器列表中。我们知道，只有一个方法(帖子）以Swagger的回应所示。
6.春季数据休息
Springfox提供支持春天数据休息通过它Springfox-data-rest图书馆。
如果它发现了春天启动将负责自动配置春天启动 - 起动器 - 数据休息在类路径中。
现在让我们创建一个名为用户:
@entity public类用户{@id私人长期ID;私有字符串名字;私人INT年龄;私有字符串电子邮件;// getters和setter}然后我们会创造UserRepository添加CRUD操作用户实体：
@Repository公共接口UserRepository扩展了CrudRepository <用户，Long> {}最后，我们将导入SpringDataRestConfiguration班上Springfoxconfig班级：
@ EnableWgger2WebMVC @import（springdatarestconfiguration.class）public类springfoxconfig {// ...}注意：我们已经使用过@ EnableWgger2WebMVC.注释要启用摇摇晃晃，因为它已更换@ EnableWagger2.在图书馆的版本3中注释。
让我们重新启动应用程序以生成Spring Data Ret API的规范：
我们可以看到Springfox为此产生了规格用户使用HTTP方法(如得到,发布，放置，补丁，和删除。
7.Bean验证
Springfox也支持bean验证通过它的注释Springfox-bean验证器图书馆。
首先，我们将添加Maven依赖于我们的pom.xml:
<依赖> io.springfox Springfox-Bean验证器 2.9.2 再一次,如果我们使用Spring Boot，我们不必明确提供上述依赖性。
接下来，让我们添加一些验证注释@notnull.和@min.到了用户实体：
@entity public类用户{// ... @notnull（message =“名字不能为null”）私有字符串名字;@min（value = 15，message =“年龄不应该小于15”）@max（值= 65，消息=“年龄不应该大于65”）私人int年龄;}最后，我们将导入BeanValidatorPluginsConfiguration班上Springfoxconfig班级：
@ EnableWagger2 @import（beanvalidatorpluginsconfiguration.class）public类springfoxconfig {// ...}让我们来看看API规范中的变化:
在这里，我们可以观察到这一点用户模特有* 必需的在这一点名。此外,最低限度和最大为此定义了值年龄。
8.插件
为了向API规范添加特定功能，我们可以创建一个Springfox插件。插件可以提供各种功能，从丰富型号和属性到自定义API列表和默认值。
Springfox通过其推荐支持插件创作spi.模块。SPI模块提供了一些类似的接口ModelBuilderPlugin,modelpropertybuilderplugin.， 和ApilistingBuilderPlugin.充当可扩展性挂钩以实现自定义插件。
为了演示这些功能，让我们创建一个插件来丰富电子邮件财产的财产用户模型。我们将使用它modelpropertybuilderplugin.接口并设置值图案和例子。
首先，让我们创造EmaidAnnotationPlugin.课程并覆盖支持允许任何方法的方法文档类型，如播放1.2和播放2：
@Component @Order(Validators.BEAN_VALIDATOR_PLUGIN_ORDER) public class EmailAnnotationPlugin implements ModelPropertyBuilderPlugin {@Override public boolean supports(DocumentationType分隔符){return true;}}然后我们会覆盖申请方法的方法modelpropertybuilderplugin.要设置构建器属性的值：
@override public void应用（modelPropertyContext上下文）{可选<电子邮件>电子邮件= AnnotationFramban（上下文，电子邮件.Class）;if（email.ispresent（））{context.getspecificationBuilder（）。facetBuilder（stringelementFacetBuilder.Class）.pattern（电子邮件.get（）。Regexp（））;context.getSpecificationBuilder（）。示例（“[电子邮件受保护]“）;}}}因此，API规范将显示图案和例子属性注释的@电子邮件注释。
接下来，我们将添加@电子邮件注释给了用户实体：
@Entity public class User{//…(regexp =".*@.*\\..*"， message = "Email应该是有效的")}最后，我们将启用EmaidAnnotationPlugin.在里面Springfoxconfig通过注册为bean来进行类:
@Import({BeanValidatorPluginsConfiguration.class}) public class SpringFoxConfig{//…@Bean public EmailAnnotationPlugin emailPlugin(){返回新的EmailAnnotationPlugin();}}我们来看看EmaidAnnotationPlugin.在行动：
我们可以看到图案相同的regex(.*@.*\\..*)来自电子邮件财产的财产用户实体。
类似地，例子([电子邮件受保护]）与定义相同申请方法的方法EmaidAnnotationPlugin.。
9.高级配置
的摘要我们的应用程序的豆可以配置为让我们更多地控制API文档生成过程。
9.1。过滤API以进行播放的响应
公开整个API的文档并不总是可取的。我们可以通过传递参数给蜜蜂（）和路径（）方法的方法摘要班级。
如上所述，RequestHandLerselectors.允许使用任何或者没有任何谓词，但也可用于根据基本包，类注释和方法注释过滤API。
PathSelectors通过谓词提供额外的过滤，扫描我们应用程序的请求路径。我们可以用任何（）,没有任何（），Regex（）， 或者ant ()。
在下面的示例中，我们将指示Swagger仅包含来自特定包的控制器，使用特定路径，使用ant ()谓语:
@Bean公共Docket api(){返回新的Docket(DocumentationType.SWAGGER_2) .select() .api (RequestHandlerSelectors.basePackage("com.baeldung.web.co金宝搏188体育ntroller")) .paths(PathSelectors.ant("/foos/*")) .build();}9.2。自定义信息
Swagger还在其响应中提供了一些默认值，我们可以自定义，例如“API文档”，“由联系电子邮件创建”，以及“Apache 2.0”。
要更改这些值，我们可以使用apiInfo (apiInfo apiInfo)方法 - 方法 -apiinfo.包含关于API的自定义信息的类:金宝搏官网188be
@Bean公共Docket api(){返回新的Docket(DocumentationType.SWAGGER_2) .select() .api (RequestHandlerSelectors.basePackage(“com.example.controller”)).paths(PathSelectors.ant(“/foo /*”)).build() .apiInfo(apiInfo());} private ApiInfo ApiInfo() {return new ApiInfo("My REST API"， "Some custom description of API."， "API TOS"， "Te188金宝搏真人荷官rms of service"， new Contact("John Doe"， "www.example.com"， "[电子邮件受保护]“），”API许可证“，”API许可证URL“，Collections.emptyList（））;}9.3。自定义方法响应消息
招摇允许全局覆盖HTTP方法的响应消息通过摘要sGlobalResponsemessage（）方法。
首先，我们需要指示摇摆权威不使用默认响应消息。假设我们想要覆盖500.和403.所有响应消息得到方法。
为此，必须将某些代码添加到摘要的初始化块(为清晰起见，原始代码被排除):
.usedeFaultResponsemessages（false）.globalResponsemessage（RequestMethod.get，NewArrayList（New OrkingEmessageBuilder（）.code（500）.message（“500消息”）.ResponseModel（新ModelRef（“错误”））.build（），新的respontemessagebuilder（）.code（403）.message（“禁止！”）.build（）））;
10.Swagger UI与OAuth-Secured API
Swagger UI提供了许多非常有用的特性，我们在这里已经很好地介绍了这些特性。但是如果我们的API是安全的且不可访问的，我们就不能真正使用其中的大部分。
让我们看看我们如何在此示例中使用授权代码授权类型允许沃克访问OAuth-Secured API。
我们将配置Swagger以使用使用的安全APISecurityScheme和SecurityContext.支持：
@bean public docket api（）{return new docket（documentationtype.swagge_2）.select（）.apis（requesthandlerselectors.any（））.paths（pathselectors.any（））.build（）.securityschemes（arrays.aslist（securityscheme（））.SecurityContexts（arrays.aslist（securityContext（）））;}10.1。安全配置
我们将定义A.安全配置在我们的Swagger配置和设置一些默认值:
@bean publice securityconfiguration security（）{returnceardconfigurationBuilder.Builder（）.ClientID（Client_ID）.clientsecret（client_secret）.copeSeparator（“”）.sebasicauthuticationwithaccesscodegrant（true）.build（）;}10.2。SecurityScheme
接下来，我们将定义SecurityScheme;这是用来描述我们的API是如何安全的(基本身份验证，OAuth2，…)。
在我们这里的例子中，我们将定义一个OAuth方案，用于保护资源服务器:
Private SecurityScheme SecurityScheme（）{granttype granttype = new authorizizationcodegrantbuilder（）.TokenEndPoint（new tokenendpoint（auth_server +“/令牌”，“oauthtoken”））.tokenRequestendpoint（new tokenrequestendpoint（auth_server +“/授权”，client_id，client_secret））。建造（）;securityscheme oauth = new oauthbuilder（）。名称（“spring_oauth”）.granttypes（arrays.aslist（granttype））.copes（arrays.aslist（scopes（））.build（）;退回OAuth;}注意，我们使用了授权代码授权类型，为此我们需要提供一个令牌端点和OAuth2授权服务器的授权URL。
以下是我们需要定义的范围：
private授权acope [] scopes（）{erizizationscope [] scopes = {new授权vope（“读取”，“为读取操作”），新授权范围（“写入”，“写入操作”），新授权（“Foo”，“foo”，“Access foo api“）};返回范围;}这些与我们在我们的应用程序中实际定义的范围同步/ foos.API。
10.3。SecurityContext.
最后，我们需要定义一个SecurityContext.对于我们的示例API:
private SecurityContext SecurityContext () {return SecurityContext.builder() . securityreferences(数组。asList(new SecurityReference("spring_oauth"， scope ()))) . forpaths (PathSelectors.regex("/foo .*"))) .build();}注意我们在参考中使用的名称如何 -spring_oauth- 与我们之前使用的名称同步SecurityScheme。
10.4。测试
现在我们已经准备好了一切，让我们看看我们的Swagger UI并尝试访问Foo API。
我们可以在本地访问Swagger UI：
http://localhost:8082/spring-security-oauth-resource/swagger-ui.html正如我们所看到的，由于我们的安全配置，一个新的授权按钮现在存在:
当我们单击“授权”按钮时，我们可以看到以下弹出窗口以授权我们的Swagger UI访问安全API：
注意：
- 我们可以看到Client_ID和Client_secret，因为我们之前预先配置了它们（但我们仍然可以更改它们）。
- 我们现在可以选择我们需要的范围。
以下是如何标记的安全API：
现在，最后，我们可以击中我们的API！
当然，它几乎不言而喻，我们需要小心我们如何在外部公开Swagger UI，现在这种安全配置处于活动状态。
11.结论
在本文中，我们设置Swagger 2以生成Spring REST API的文档。我们还探索了可视化和定制蜂鸣器的输出的方法。最后，我们查看了一个简单的OAuth配置令人震撼。
的全面实施本教程可以找到GitHub项目。要在引导项目中查看设置，请退房这个github模块。
对于OAuth部分，我们的代码可用Spring-Security-OAuth存储库。
如果你是学生与春天的休息，从模块7上达第1课，以深入潜入春天和春靴。
