springBoot集成swagger2在线生成API接口

最新推荐文章于 2023-04-20 16:00:03 发布

肥仔哥哥1930

最新推荐文章于 2023-04-20 16:00:03 发布

阅读量673

点赞数

分类专栏： springboot 文章标签：在线API查看 swagger springboot集成swagger

本文链接：https://blog.csdn.net/zwrlj527/article/details/89192109

版权

springboot 专栏收录该内容

24 篇文章 0 订阅

订阅专栏

场景

相信很多后端开发最烦的就是写文档，感觉文档比代码难写的有没有？在遇到前端小姐姐/测试小姐姐要接口文档的时候是不是特别难受香菇。今天就来说说解救广大后端人员的福音。

一，Swagger2集成jar引入（我们用maven管理jar）

pom增加：

<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>

二，增加配置（我目前的项目是springBoot）

@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurer {

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/"); //注册静态资源目录
registry.addResourceHandler("/webjars/**") //一定注意路径是/webjars/**
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
//可以注入多个doket，也就是多个版本的api，可以在看到有三个版本groupName不能是重复的，v1和v2是ant风格匹配，配置文件
@Bean
public Docket api() {
//可以添加多个header或参数
ParameterBuilder aParameterBuilder = new ParameterBuilder();
aParameterBuilder
.parameterType("header") //参数类型支持header, cookie, body, query etc
.name("token") //参数名
.defaultValue("token") //默认值
.description("header中token字段测试")
.modelRef(new ModelRef("string"))//指定参数值的类型
.required(false).build(); //非必需，这里是全局配置，然而在登陆的时候是不用验证的
List<Parameter> aParameters = new ArrayList<Parameter>();
aParameters.add(aParameterBuilder.build());
return new Docket(DocumentationType.SWAGGER_2)
       .groupName("v1")
       .select()
       .apis(RequestHandlerSelectors.any()) //设置包过滤
.paths(PathSelectors.any()) //设置方法requestMapping过滤
.build()
.apiInfo(apiInfo1())
.globalOperationParameters(aParameters); //设置是否需要token验证
}

private ApiInfo apiInfo1() {
return new ApiInfoBuilder()
.title("手机运营端Api 0.01")
.termsOfServiceUrl("www.example.com")
.contact(new Contact("zhengwen","https://blog.csdn.net/zwrlj527","zwsky88@126.com"))
.version("v0.01")
.build();
}
}

WebMvcConfigurer 注意最好是用这个，WebMvcConfigurerAdapter这个目前已过时，看我用的jar版本就知道，我不喜欢用旧的。WebMvcConfigurationSupport用这个容易后面容易出现No mapping for GET /webjars/的问题，哪怕你注册了静态文件映射。

@EnableSwagger2这个注解别忘记了哦，这个意思是开启Swagger2

其他基本每一行都有注释，注意RequestHandlerSelectors和PathSelectors，之前就呗这里坑了，这里一个是设置包扫描范围，一个是设置方法名范围

三，接口相关的修改

controller的注解标签首先是使用@RestController，目前前后端分离估计都是用的这个了。
然后加上@Api(value = "租户合同API")

方法上增加：

@ApiOperation(value="获取合同列表", notes="获取合同列表")
@ApiImplicitParams({
@ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "String",paramType = "path"),
@ApiImplicitParam(name = "companyId", value = "项目ID", required = true, dataType = "String",paramType = "path"),
@ApiImplicitParam(name = "status", value = "合同状态", required = true, dataType = "String",paramType = "path"),
@ApiImplicitParam(name = "page", value = "页码", required = false, dataType = "int",paramType = "RequestParam"),
@ApiImplicitParam(name = "size", value = "每页显示数量", required = false, dataType = "int",paramType = "RequestParam")
})
@GetMapping("/getSubscribeList/{userId}/{companyId}/{status}")
public Result<?> getSubscribeList(@PathVariable String userId,@PathVariable String companyId,@PathVariable String status,@RequestParam(defaultValue = "0") Integer page, @RequestParam(defaultValue = "0") Integer size) {
//TODO your business code

}

@ApiOperation作用是后面可以在页面上看到方法的描述

@ApiImplicitParams作用也是介绍接口入参的，

@ApiImplicitParam单个参数的描述，

注意里面的name值要与参数对应，value是描述，到时候入参表单上的输入框会显示对应的描述。required这个就是是否必传，应该不需要解释，dataType数据类型，注意这里好像有的包装类型没有，比如int的Integer，如果写这个后面在页面做尝试调用的时候有警告。paramType这个里面感觉就是随便写了，也就是描述参数类型，比如我这里写path意思是在路径上，写RequestParam表示是在?后面。

四，启动springboot增加注解

同样的也是在springboot的application类上增加@EnableSwagger2

五，启动看效果