SpringBoot集成Swagger2

1 前言

• 1.1 用途：在项目中集成Swagger自动在线测试API文档
• 1.2使用条件：jdk 1.8 + 否则swagger2无法运行

2 引入依赖

#本配置是基于springboot2.2.5.RELEASE
<!-- 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>

3编写相关配置

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {


}

说明 现在我们就可以访问http://ip:端口号/项目名/swagger-ui.html ，可以看到swagger的界面；

4 对3中配置进行高级一点的配置

4.1配置介绍

@Configuration
//注解开启 swagger2 功能
@EnableSwagger2
public class SwaggerConfig {

    //是否开启swagger，正式环境一般是需要关闭的
    @Value("${swagger.enabled}")
    private boolean enableSwagger;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("松哥哥团队")
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                .enable(enableSwagger)
                .select()//下面配置基于此方法返回的对象
                
//（常） 扫描所有，项目中的所有接口都会被扫描到 RequestHandlerSelectors.any() 
// 不扫描接口RequestHandlerSelectors.none() 
// 通过方法上的注解扫描，RequestHandlerSelectors.withMethodAnnotation(final Class<? extends Annotation> annotation)，如withMethodAnnotation(GetMapping.class)只扫描get请求
// 通过类上的注解扫描，RequestHandlerSelectors.withClassAnnotation(final Class<? extends Annotation> annotation)，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
//（常） 根据包路径扫描接口RequestHandlerSelectors.basePackage(final String basePackage)
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))

// （常）任何请求都扫描 PathSelectors.any("/kuang/**") 只扫描请求以/kuang开头的接口
// 任何请求都不扫描 PathSelectors.none() 
// 通过正则表达式控制 PathSelectors.regex(final String pathRegex)
// 通过ant()控制 PathSelectors.ant(final String antPattern) 
                .paths(PathSelectors.any())//与apis()配置一个即可
                .build();
    }

//设置ui页面头显示的东西，也相当于对本页面的一个说明吧
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot中使用Swagger2构建RESTful接口")
                //文档描述
                .description("接口说明")
                //服务条款URL
                .termsOfServiceUrl("http://127.0.0.1:8080/")
                //联系信息
                .contact(new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱"))
                //版本号
                .version("1.0。0")
                .build();
    }

}

4.2配置后显示效果

5 多个团队同时开发，不想看到同样的api怎么办？

• 还是在刚刚的配置文件中配置多个Docket(）和多个apiInfo()一一对应即可。

@Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("松哥哥团队")
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                .enable(true)
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(any())
                //指定路径处理PathSelectors.any()代表所有的路径
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot中使用Swagger2构建RESTful接口")
                //文档描述
                .description("接口说明")
                //服务条款URL
                .termsOfServiceUrl("http://127.0.0.1:8080/")
                //联系信息
                .contact(new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱"))
                //版本号
                .version("1.0。0")
                .build();
    }

    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("松哥哥团队2")
                .apiInfo(apiInfo2());
    }

    private ApiInfo apiInfo2() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot中使用Swagger2构建RESTful接口")
                //文档描述
                .description("接口说明")
                //服务条款URL
                .termsOfServiceUrl("http://127.0.0.1:8080/")
                //联系信息
                .contact(new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱"))
                //版本号
                .version("1.0。0")
                .build();
    }

6 注解介绍

• 个人理解：注解只是对各个接口或者参数或者实体类或者属性说明解释并且加以限制，使内容更加清晰明了，只要启动Swagger其实已经产生API文档。

• 常用注解（带*表示常用）

注解	说明
*@Api()	用于controller类上, tags=“说明该类的作用，可以在UI界面上看到的注解”;value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”
*@ApiOperation()	用在controller的方法上, value=“说明方法的用途、作用”;notes=“方法的备注说明”
*@ApiImplicitParam()	作用在方法上，表示单独的请求参数;.1. name ：参数名。2. value ： 参数的具体意义，作用。3. required ： 参数是否必填。4. dataType ：参数的数据类型。5. paramType ：查询参数类型，
*@ApiImplicitParams()	用于方法，多个@ApiImplicitParam() 例如：@ApiImplicitParams({@ApiImplicitParam(…),@ApiImplicitParam(…)})
@ApiResponse()	用于方法，描述操作的可能响应。例如：@ApiResponse(code = 500, message = “2001:因输入数据问题导致的报错”)
@ApiResponses（）	用于方法，一个允许多个@ApiResponse对象列表的包装器。例如：@ApiResponses(value = { @ApiResponse(code = 500, message = “2001:因输入数据问题导致的报错”),@ApiResponse(code = 500, message = “403:没有权限”)})
@ApiIgnore	忽略这个API，不会生成接口文档。可注解在类和方法上，导入的包import springfox.documentation.annotations.ApiIgnore;
	以下用在实体类上
*@ApiModel()	用对象类上，描述一个Model的信息
*@ApiModelProperty()	用对象类的字段上,value = 字段说明;name = 重写属性名字;dataType = 重写属性类型;required = 是否必填，true必填;example = 举例说明;hidden = 隐藏

提示注解的例子请访问https://blog.csdn.net/java_yes/article/details/79183804?utm_medium=distribute.pc_relevant.none-task-blog-BlogCommendFromMachineLearnPai2-1.edu_weight&depth_1-utm_source=distribute.pc_relevant.none-task-blog-BlogCommendFromMachineLearnPai2-1.edu_weight