1 介绍
开发前后端分离架构的项目,往往调试后端Web接口需要用到POSTMAN工具。虽然POSTMAN 工具的功能非常强大,但是请求参数很多的情况下,我们手写这些参数和数据还是非常麻烦的。 因此我们需要一个调试后端Web接口更加简便的方法。恰好Swagger提供了REST API调用方 式,我们不需要借助任何工具的情况下,访问Swagger页面,就可以对Web接口进行调用和调试,这种调试方式的效率要远超POSTMAN软件。
2 使用
1 导入依赖
<!-- 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>
2 创建Swagger配置类
-
在config的包下创建配置类SwaggerConfig
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { // 构建swagger页面信息 ApiInfo apiInfo = new ApiInfoBuilder() .title("EMOS在线办公系统") .description("简单方便的办公系统") .termsOfServiceUrl("http://127.0.0.1:8080") .version("v1.0") .build(); Docket docket = new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo) .select() .paths(PathSelectors.any()) //扫描所有路径 //使用@ApiOperation的方法会被提取到REST API中 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .build(); /* * 下面的语句是开启对JWT的支持,当用户用Swagger调用受JWT认证保护的方法, * 必须要先提交参数(例如令牌) */ //存储用户必须提交的参数 List<ApiKey> apiKeyList = new ArrayList<>(); //规定用户需要输入什么参数 ApiKey apiKey = new ApiKey("token", "token", "header"); apiKeyList.add(apiKey); docket.securitySchemes(apiKeyList); //如果用户JWT认证通过,则在Swagger中全局有效 AuthorizationScope scope = new AuthorizationScope("global", "accessEverything"); AuthorizationScope[] scopes = {scope}; //存储令牌和作用域 SecurityReference reference = new SecurityReference("token", scopes); List<SecurityReference> refList = new ArrayList<>(); refList.add(reference); SecurityContext context = SecurityContext.builder().securityReferences(refList).build(); List<SecurityContext> cxtList = new ArrayList<>(); cxtList.add(context); docket.securityContexts(cxtList); return docket; } }
-
编写controller测试
@RestController @RequestMapping("/test") @Api("测试Web接口") public class TestController { @GetMapping("/sayHello") @ApiOperation("最简单的测试方法") public R sayHello(Action action) { return R.ok().put("message", "HelloWorld").put("action",action); } }
3 注解说明
@Api:用在Controller控制器类上 属性tags="说明该类的功能及作用" @ApiOperation:用在Controller控制器类的请求的方法上 value="说明方法的用途、作用" notes="方法的备注说明" @ApiImplicitParams:用在请求的方法上,表示一组参数说明 @ApiImplicitParam:请求方法中参数的说明 name:参数名 value:参数的汉字说明、解释、用途 required:参数是否必须传,布尔类型 paramType:参数的类型,即参数存储位置或提交方式 · header --> Http的Header携带的参数的获取:@RequestHeader · query --> 请求参数的获取:@RequestParam (如上面的例子) · path(用于restful接口)--> 请求参数的获取:@PathVariable · body(不常用) · form(不常用) dataType:参数类型,默认String,其它值dataType="Integer" defaultValue:参数的默认值 @ApiResponses:用在控制器的请求的方法上,对方法的响应结果进行描述 @ApiResponse:用于表达一个响应信息 code:数字,例如400 message:信息,例如"请求参数没填好" response:响应结果封装类,如上例子中的AjaxResponse.class @ApiModel:value=“通常用在描述@RequestBody和@ResponseBody注解修饰的接收参数或响应参数实体类” @ApiModelProperty:用在实体类的属性上,value="实体类属性的描述"
注意:
报错:Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
可以降低boot版本,或者在配置文件中添加
spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER