【Swagger】一小时掌握Swagger对接SpringBoot

为什么要用Swagger？

Swagger是一个高效优秀的接口文档工具，可以帮助项目更好的迭代版本，更方便的测试接口，更实时更清晰的接口文档工具。


解决痛点：

1. 减少前后端开发交接的工作量
2. 后端开发，修改接口，swagger可以实时的更新，前端再也不用担心接口变动
3. 方便测试小伙伴接口测试，传统接口测试使用postman，虽然性能比较高，但是效率底下

SpringBoot整合Swagger

（1）maven引入依赖包

这里需要注意swagger2.X版本和3.X版本引入依赖的包不一样

1. swagger 2.X版本引入依赖：

		<!-- swagger2.X 配置 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.5.0</version>
        </dependency>
        <!-- swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.5.0</version>
        </dependency>

2. swagger 3.X版本引入依赖：

		<!-- swagger3.0配置 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

（2）SwaggerConfig配置类

1. swagger 2.X

@Configuration
@EnableSwagger2   //开启swagger 2.X    请求地址：http://localhost:8080/swagger-ui.html
public class SwaggerConfig {
}

2. swagger 3.X

@Configuration
@EnableOpenApi      //开启swagger 3.X   请求地址：http://localhost:8080/swagger-ui/index.html
public class SwaggerConfig {
}

经过如上配置，swagger的页面已经可以正常访问了

（3）定制Swagger文档

配置SwaggerConfig文档默认分组的样式

@Configuration
@EnableOpenApi      //开启swagger 3.0.0
public class SwaggerConfig {

    /**
     * 可以配置多个分组
     * 
     * @return
     */
    @Bean
    public Docket docket_other(){
        return new Docket( DocumentationType.SWAGGER_2 ).groupName( "other" );
    }

 	/**
     * 定制默认分组
     * 
     * @param env 项目环境变量
     * @return
     */
    @Bean
    public Docket docket(Environment env){
        // 生产环境 or 测试环境
        // boolean isDevOrPro = env.acceptsProfiles( Profiles.of( "dev" ) );
        boolean isDevOrPro = true;

        Docket docket = new Docket( DocumentationType.SWAGGER_2 )
                .apiInfo( apiInfo() )
                // 是否开启swagger，，，dev开启，pro关闭
                .enable( isDevOrPro )
                .select()
                // RequestHandlerSelectors 配置扫描接口的方式
                // 1、.basePackage( "com.example.swagger_demo.controllers" )  指定扫描的包
                // 2、.any()                                                  扫描所有包
                // 3、.none()                                                 全都不扫描
                // 4、.withClassAnnotation( RestController.class )            扫描类的注解
                // 5、.withMethodAnnotation( GetMapping.class )               扫描方法的注解
                .apis( RequestHandlerSelectors.basePackage( "com.example.swagger_demo.controllers" ) )
                .build();
        return docket;
    }

    /**
     * 配置swagger文档基本信息
     *
     * @return ApiInfo
     */
    public ApiInfo apiInfo(){
        // 作者信息
        Contact contact = new Contact( "唐", "https://blog.csdn.net/m0_46537958/article/details/113077994", "1430482733@qq.com" );
        ApiInfo apiInfo = new ApiInfo(
                "自定义api文档标题",
                "自定义api文档描述",
                "v100.0(自定义版本信息)",
                "https://blog.csdn.net/m0_46537958/article/details/113077994",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
        return apiInfo;
    }
}

配置成功页面显示：

（4）接口配置

HelloWorldApi.java

@Api(tags = "你好世界接口")
@RestController
public class HelloWorldApi {

    @GetMapping("/hello")
    public String hello() {
        return "hello";
    }

    @ApiOperation( value = "登陆", notes = "登陆备注信息", httpMethod = "get" )
    @GetMapping("/login")
    public ArrayList<UserPojo> login(
            @ApiParam(name = "username", value = "登录名", required = true) String username,
            @ApiParam(name = "password", value = "密码", required = true) String password
    ) {
        ArrayList<UserPojo> userPojos = new ArrayList<>();
        for (int i = 0; i < 10; i++) {
            UserPojo user = new UserPojo();
            user.username = "张三";
            user.password = "123456"+i;
            userPojos.add( user );
        }
        return userPojos;
    }

}

接口显示效果如下：

UserPojo.java

@ApiModel("UserPojo(登陆用户)")
public class UserPojo {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

配置的返回类如下：