Java后端入职第八天，配置Swagger接口文档（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: true

application-pro.yaml配置swagger为false 

swagger:
  enable: false

3.动态修改application.yaml环境配置

其实有两种方式进行修改

一种是直接通过配置中心动态修改，项目部署上线之后，想要在在正式环境访问的话，直接修改application-pro.yaml配置swagger为true。

另一种就是同个maven构建打包的时候，自动切换读取对应的配置文件

五、总结

本文主要讲了如何配置swagger接口文档，以及如何控制不同环境访问，一般开发，根据个人经验，除非新工程，才需要配置swagger，不然都是已经大佬搭建好了，我们只要熟悉使用swagger相关注解，按照规范进行定义接口。不过控制不同环境访问，这个是我工作中遇到的，很多大佬搭建的时候，都没在意，而且网上方法也是参差不齐，