SpringBoot-整合Swagger2
swagger2是一个用于生成、并能直接调用的可是话restful风格的服务
下面贴出springboot整合swagger2代码
一、maven依赖
这里使用的spring-boot版本是2.1.1.RELEASE,swagger2使用的是2.9.2,我一开始用的springboot1.5.6.RELEASE,swagger从2.4到2.9.2都用了,结果又很多jar包冲突,springboot换成了2.*版本依旧,依然有jar冲突,无奈,只能把冲突的依赖找出来,有具体报错信息,把他exclude掉就行,而且idea的maven-helper插件帮助也蛮大
<!-- swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> <exclusions> <exclusion> <artifactId>spring-context</artifactId> <groupId>org.springframework</groupId> </exclusion> <exclusion> <artifactId>spring-beans</artifactId> <groupId>org.springframework</groupId> </exclusion> <exclusion> <artifactId>spring-aop</artifactId> <groupId>org.springframework</groupId> </exclusion> </exclusions> </dependency> <!-- swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
二、swagger2配置
package com.hy.other.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfiguration { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() // 生成api的包路径(一般是我们controller包的路径) .apis(RequestHandlerSelectors.basePackage("com.hy.other.controller")) .paths(PathSelectors.any()) .build(); } // swagger ui 页面里面的一些信息 private ApiInfo apiInfo() { return new ApiInfoBuilder() // 页面标题 .title("spring boot swagger") // 创建人 .contact(new Contact("hy", "https://www.cnblogs.com/xhy-shine", "")) // 版本号 .version("1.0") // 描述 .description("API接口文档") .build(); } }
注意:@EnableSwagger2一定要加上,不然会无法访问swagger的ui界面,会报如下错误
三、代码(主要是swagger2的注解)
注解有挺多的,比较常用的就是@Api、@ApiOperation、@ApiImplicitParam、@ApiModel、@ApiModelProperty
@Api:包括下面的所有接口,有点类注释的意思
@ApiOperation:给接口增加说明
@ApiImplicitParams、@ApiImplicitParam:给接口参数添加说明
@ApiModel:描述对象类型的请求参数
@ApiModelProperty:描述对象的属性
注意:@ApiModelProperty注解的参数说明
paramType:指定参数放在哪个地方(header:request header中,使用@RequestHeader获取;query:使用@RequestParam获取;path:使用@PathVariable获取;body、form两者不常用)可参考:https://swagger.io/docs/specification/describing-parameters/
name:参数名
dataType:参数类型
required:是否必须
value:参数的意思
defaultValue:默认值
package com.hy.other.controller; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiOperation; import org.springframework.amqp.rabbit.core.RabbitTemplate; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.beans.factory.annotation.Value; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; @Api(description = "MQ接口") @RestController @RequestMapping("/messageQueue") public class MessageQueueController { @Value("${rabbitmq.exchangeName}") private String exchangeName; @Value("${rabbitmq.queueName}") private String queueName; @Value("${rabbitmq.routeKey}") private String routeKey; @Autowired private RabbitTemplate rabbitTemplate; @ApiOperation(value = "send message to spin", notes = "发送消息到spin") @ApiImplicitParam(name = "message", value = "消息内容", required = true, paramType = "query") @RequestMapping("/sendWso2ToSpin") public String sendWso2ToSpin(@RequestParam("message") String message) { rabbitTemplate.convertAndSend(exchangeName, routeKey, message); return message; } }
访问地址你的项目根路径加上swagger-ui.html就行
1、swagger会根据@RequestParam、@RequestBody注解来决定用form提交还是application/json格式(上图出现Parameter content type为application/json是因为我把请求参数前的注解改成了@RequestBody)
2、会根据@RequestMapping、@PostMapping、@GetMapping等注解生成对应的请求,如上,我写的@RequestMapping,他把所有请求格式都生成了
3、如果接收的是对象,可以使用@ApiModel结合@ApiModelProperty