Sprngboot配置Swagger接口文档
原创
一、背景
小明今天要跟前端同学对接，发现接口，都是直接同个微信或者qq发给他，效率很低，而且前端同学也不能测试调用，在对接过程很麻烦，也很费时，他现在很苦恼，大家有什么好的接口文档工具推荐了。
其实现在已经有很多文档对接的工具了，以前使用的是国外的postman，到现在国内的apipost或者apifox等等，或者代码接口集成工具swagger。今天给初入职场的同学们，介绍一下如何整合Swagger以及如何配置指定环境访问。
二、整合Swagger
1.工程pom引入swagger依赖
<!-- 整合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.新增SwaggerConfig配置文件
主要是配置swagger文档扫描的包和方法
@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//加了ApiOperation注解的类，才生成接口文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//包下的类，才生成接口文档
//.apis(RequestHandlerSelectors.basePackage("io.renren.controller"))
.paths(PathSelectors.any())
.build()
.securitySchemes(security());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文档")
.description("swagger接口文档")
.version("3.0.0")
.build();
}
private List<ApiKey> security() {
return newArrayList(
new ApiKey("token", "token", "header")
);
}
}这里要注意的是，不要在启动类添加@EnableSwagger2，这样会导致整个工程所有接口都生成了swagger文档。
3.控制层编写接口
@Api("APP测试接口")：标注接口类，说明改类做什么
@ApiOperation(value = "登录接口", notes = "登录接口")：标注每个方法，说明改接口方法用途
@ApiImplicitParam(name = "name", value = "用户名",required = true, type = "string")：标记方法参数
@Api("APP测试接口")
@RestController
public class SwaggerController {
@ApiOperation(value = "登录接口", notes = "登录接口")
@ApiImplicitParam(name = "name", value = "用户名",
required = true, type = "string")
@GetMapping("/swagger/login")
public String login(String name){
return "登录成功 ：" + name;
}
}三、启动工程，Swagger文档调用接口
启动项目工程，浏览器访问地址：
http://localhost:端口号/swagger-ui.html#/
点击对应接口，展开进行调试，发现可以正常调用接口
四、配置swagger指定环境访问
以上基本是完成了swagger的配置了，但是一般项目开发，为了安全起见，会禁止正式环境的访问，或者同个配置中心开启。接下来给大家介绍一下，如何动态设置swagger环境访问。
1.添加配置属性
在SwaggerConfig配置文件类前中添加注解，指定swagger.enable属性，为true，改配置类才生效
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")2.新建不同环境配置文件
主application.yaml文件中添加配置环境，这样启动工程就会，springboot就会自动拼接：application-dev.yaml、application-test.yaml、application-pro.yaml，然后根据profiles配置读取对应的配置文件，
spring:
profiles:
# #在此选择环境 dev test pro
active: dev新建不同环境的application.yaml文件，后缀由dev、test、pro
application-dev.yaml配置swagger为true
swagger:
enable: trueapplication-pro.yaml配置swagger为false
swagger:
enable: false3.动态修改application.yaml环境配置
其实有两种方式进行修改
一种是直接通过配置中心动态修改，项目部署上线之后，想要在在正式环境访问的话，直接修改application-pro.yaml配置swagger为true。
另一种就是同个maven构建打包的时候，自动切换读取对应的配置文件
五、总结
本文主要讲了如何配置swagger接口文档，以及如何控制不同环境访问，一般开发，根据个人经验，除非新工程，才需要配置swagger，不然都是已经大佬搭建好了，我们只要熟悉使用swagger相关注解，按照规范进行定义接口。不过控制不同环境访问，这个是我工作中遇到的，很多大佬搭建的时候，都没在意，而且网上方法也是参差不齐，
原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。
如有侵权，请联系 cloudcommunity@tencent.com 删除。
原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。
如有侵权，请联系 cloudcommunity@tencent.com 删除。
腾讯云开发者
