springboot整合swagger实现接口文档

作为后端程序员，有时候很烦自己接口文档写的不好，不如学一学项目中整合swagger，让程序帮你写。

1.导入依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2.编写配置文件

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2 //开启Swagger2
@ComponentScan("com.summer.controller")//新增
public class SwaggerConfig {
//    //多个Docket实现多组
//    @Bean
//    public Docket docket1(){
//        return new Docket(DocumentationType.SWAGGER_2).groupName("A")
//                .select()
//                .apis(RequestHandlerSelectors.none())
//                .build();
//    }
//    @Bean
//    public Docket docket2(){
//        return new Docket(DocumentationType.SWAGGER_2).groupName("B")
//                .select()
//                .apis(RequestHandlerSelectors.none())
//                .build();
//    }
//    @Bean
//    public Docket docket3(){
//        return new Docket(DocumentationType.SWAGGER_2).groupName("C")
//                .select()
//                .apis(RequestHandlerSelectors.none())
//                .build();
//    }



    //配置了Swagger的Bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的Swagger环境
        Profiles prfiles= Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断是否出处在自己设定的环境当中
        boolean flag=environment.acceptsProfiles(prfiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("xxx")
                .enable(true)//enable是否启动Swagger，如果为false不启动，则不能在浏览器里访问Swagger如果为true启动Swagger
                .select()
                //RequestHandlerSelectors 扫描要配置接口的方式
                //basePackage 指定要扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.summer.controller"))
                //any():扫描全部
                //none():全不扫描
                //withClassAnnotation:扫描类上的注解
                //withMethodAnnotation:扫描方法上的注解
                //.apis(RequestHandlerSelectors.any())
                //paths():过滤路径
               // .paths(PathSelectors.ant("/controller/"))
                .build();
    }
    //配置Swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact=new Contact("Teamwork","http://www.apache.org/licenses/LICENSE-2.0","");
        return new ApiInfo("xxx的xxx文档",
                "xxx",
                "v1.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

3.接着在controller类上加上几个注解，以下是一个demo例子

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
@Api(value = "TbRoleController", description = "权限api")
public class TbRoleController {
    @Autowired(required =false)
    private TbRoleMapper tbRoleMapper;
    @ApiOperation("测试swagger")
    @PostMapping("/aa/bb")
    @ResponseBody
    public String addaa( ) throws IOException, TokenExpiredException {
  	return "hello world";
    }

4.最后在启动项目输入地址跳转到swagger的测试地址

地址为: htttp://ip地址:端口号/swagger-ui.html

5.常用注解

Swagger的所有注解定义在io.swagger.annotations包下
下面列一些经常用到的，未列举出来的可以另行查阅说明：

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
–	–
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
–	–
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

6.springmvc配置swagger

<!--添加swagger配置-->
<!-- 引入swagger相关 -->
<bean class="com.java5678.config.MySwagger"/>
    <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />
    <bean class="springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration" id="swagger2Config"/>
<!--其他的跟springboot一样（注意在springmvc的配置文件applicationContext.xml里弄）-->

7.参考资料

b站：狂神说java
https://www.bilibili.com/video/BV1Y441197Lw