一、简述
开发前后端分离架构的项目,往往调试后端Web接口需要用到POSTMAN工具。虽然POSTMAN工具的功能非常强大,但是请求参数很多的情况下,我们手写这些参数和数据还是非常麻烦的。因此我们需要一个调试后端Web接口更加简便的方法。恰好Swagger提供了RESTAPI调用方式,我们不需要借助任何工具的情况下,访问Swagger页面,就可以对Web接口进行调用和调试,这种调试方式的效率要远超POSTMAN软件。
二、pom.xml中导入Swagger的依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
三、创建Swagger的配置类
@Configuration @EnableSwagger2 public class SwaggerConfig { //java项目www.fhadmin.org @Bean public Docket createRestApi() { Docket docket = new Docket(DocumentationType.SWAGGER_2); // ApiInfoBuilder 用于在Swagger界面上添加各种信息 ApiInfoBuilder builder = new ApiInfoBuilder(); builder.title("XXXX系统"); ApiInfo apiInfo = builder.build(); docket.apiInfo(apiInfo); // ApiSelectorBuilder 用来设置哪些类中的方法会生成到REST API中 ApiSelectorBuilder selectorBuilder = docket.select(); selectorBuilder.paths(PathSelectors.any()); //所有包下的类 //使用@ApiOperation的方法会被提取到REST API中 selectorBuilder.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)); docket = selectorBuilder.build(); /* * 下面的语句是开启对JWT的支持,当用户用Swagger调用受JWT认证保护的方法, * 必须要先提交参数(例如令牌) */ //存储用户必须提交的参数 List<ApiKey> apikey = new ArrayList(); //规定用户需要输入什么参数 apikey.add(new ApiKey("token", "token", "header")); docket.securitySchemes(apikey); //如果用户JWT认证通过,则在Swagger中全局有效 AuthorizationScope scope = new AuthorizationScope("global", "accessEverything"); AuthorizationScope[] scopeArray = {scope}; //存储令牌和作用域 SecurityReference reference = new SecurityReference("token", scopeArray); List refList = new ArrayList(); refList.add(reference); SecurityContext context = SecurityContext.builder().securityReferences(refList).build(); List cxtList = new ArrayList(); cxtList.add(context); docket.securityContexts(cxtList); return docket; } }
四、测试Web接口
package com.gaoyang.emos.wx.controller; import com.gaoyang.emos.wx.common.util.ResponseResult; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; //java项目www.fhadmin.org @RestController @RequestMapping("/test") @Api("测试Web接口") public class TestController { @RequestMapping("testSwagger") @ApiOperation("测试Swagger配置") public ResponseResult testSwagger(){ return ResponseResult.error(200,"OK"); } }
五、访问swagger-ui.html页面
注意:还需要添加在启动类中添加 @EnableSwagger2 注解,,否则会出线,页面加载失败情况!
启动项目之后,访问: http://localhost:8080/emos-wx-api/swagger-ui.html