SpringBoot整合Swagger2
一、swagger介绍
swagger 之前: 我们需要针对每一个接口去编写 接口文档，而且随着接口的修改接口文档也可能需要相应的修改。接口文档中 包含：接口功能、请求参数、返回数据、及其中每条数据的意义。
swagger之后: 我们不需要在编写独立的接口文档、只需要在相应 请求对象、返回对象、接口中加入swagger的注解 ！@Model 、@ApiProperty、@Api 、@ApiOperation.....
并且，swagger并非只能代替接口文档、还能PostMan用来简单测试、而且不用关心uri的问题。
二、swagger的demo
1、引入jar(这里使用的Maven)
|
<!--版本是2.9.2 ，有反应说Swagger2.5之前有坑，没测试过，知道有坑不用那个就行了，毕竟只是工具--> <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配置类
|
@Configuration @EnableSwagger2 public class Swagger2Config { ? @Bean public Docket createRestApi(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()).select() //RequestHandlerSelectors.basePackage("com.lyg") 将指定包下的接口教给swagger管理 //RequestHandlerSelectors.any() 将所有接口都交给swagger管理 .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } ? @SuppressWarnings("deprecation") private ApiInfo apiInfo(){ //描述信息 return new ApiInfoBuilder() .title("spring boot 集成 swager2") .description("这是2020年的一个项目") .termsOfServiceUrl("http://www.qbbzs.top") .contact("tian") .version("1.0").build(); } |
3、编写Controller类
|
@RestController @Api(value = "test swaggr") public class MongoRest { @Autowired private MongoTemplate mongoTemplate ; ? @GetMapping("/abc") @ApiOperation(value = "集成swagger服务",notes = "明天会更好") public String findMongo(@RequestParam String name){ return name + " >>> 明天会更好"; } } |
启动SpringBoot项目,访问http://localhost:8080/swagger-ui.html
三、更多swagger注解
|
/** * Swagger注解用法： * * @Api：修饰整个类，描述Controller的作用 * @ApiOperation：描述一个类的一个方法，或者说一个接口 * @ApiParam：单个参数描述 * @ApiModel：用对象来接收参数 * @ApiProperty：用对象接收参数时，描述对象的一个字段 * @ApiResponse：HTTP响应其中1个描述 * @ApiResponses：HTTP响应整体描述 * @ApiIgnore：使用该注解忽略这个API * @ApiError ：发生错误返回的信息 * @ApiImplicitParam：一个请求参数 * @ApiImplicitParams：多个请求参数 */ |
四、假如实际开发中 会产生500个Controller类。那么只能在页面进行搜索相应的 Controller类信息找到测试接口 , 如果不想搜索那就需要对所有Controller进行分类。在swaggerConfig类中追加…
|
//配置swagger分栏 @Bean public Docket createRoadRestApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("指数平台数据插入") .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.lyg.rtt")) .paths(PathSelectors.any()) //在每一个请求中都添加token栏,如果不想配置可以删除build()之后代码。 .build().globalOperationParameters(buildParameterBuilder()); }
//swagger添加token输入框 private List<Parameter> buildParameterBuilder() { ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<>(); tokenPar.name("token").description("授权").modelRef(new ModelRef("string")).parameterType("header").required(false).build(); pars.add(tokenPar.build());
return pars; } |
五、效果对比
