SpringBoot 整合Swagger

swaggle

前后端分离：

问题：

前后端集成联调，前后端难以做到“及时协调”，矛盾出现

解决：

指定schema[计划提纲],及时更新最新api，降低集成的风险

前端：postman

后端：提供接口，需要实时更新最新的消息及其改动

简介：

号称世界上最流行的Api框架

RestFul Api 文档在线自动生成工具 => api文档和api定义在线同步进行更新

直接运行，可以在线测试api接口

支持多种语言：（java、PHP）

简单进行配置后使用相关注解即可进行使用

官网：https://swagger.io/

依赖：

<!-- 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>
    
<!--新增解决 parameter type integer 报错的配置 -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>

 

配置SwaggerConfig:

 

配置后

效果：baseUrl/swagger-ui.html

 

运行后即可打开：

 

配置：

Swagger的bean实例Docket：

一个Docket实例实际上就是一个分组 ---实际开发中用于区分开发人员或者项目分组

其实主要信息也就标题和描述而已

@Configuration
@EnableSwagger2         //开启Swagger2
public class SwaggerConfig {
​
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())  //进去方法的实现类中去摸索一下
                //尝试关闭
                .groupName("良夜")  //设置当前Docket实例的分组名为  良夜
                .enable(false)  //enable为false则不能在浏览器中访问swagger文档,可以配合上判断当前项目环境来进行使用
                .select()
        /**
         *RequestHandleSelectors，配置要扫描接口的方式
         * basePackage:指定要扫描的包
         * any():扫描全部
         * none():不扫描
         * withClassAnnotation():扫描类上注解,参数是一个注解的反射对象
         * withMethodsAnnotation:扫描方法上的注解
         */
        .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                //设置要过滤的路径
                //.paths(PathSelectors.ant("/hello/**"))
                .build();
    }
​
    private ApiInfo apiInfo(){  // 设置下文档的文件信息 ApiInfo
        /**
         * 作者信息
         */
        Contact contact = new Contact("liangye","http://liangye-xo.xyz","2252578955@qq.com");
        /**
         * 配置swagger的文件信息
         */
        return new ApiInfo(
                "良夜的Api文档",
                "这个博主有点帅",
                "v1.0",
                "http://liangye-xo.xyz",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}
​

 

配置扫描接口：

设置ApiInfo(*).enable(false)后效果：

😱 Could not render e, see the console.

Docket.select()

.build();

 

设置swagger在项目环境中可使用，在生产上线时关闭

设置多个yml配置文件，在主yml中通过spring.profiles.active来设置要启动的yml（注意下yml的命名格式）

然后再配置文件SwaggerConfig中来监听当前环境即可

//获取当前项目的环境,以便管理swagger的开闭
Profiles profiles = Profiles.of("dev","test");  //接口方法的实现类
//通过environment.acceptsProfiles判断当前环境是否处在自己所设定的环境中
Boolean flag = environment.acceptsProfiles(profiles);

 

//设置api文档的分组
.groupName("良夜")

设置多个api文档的分组---设置多个Docket实例后托管于SpringBoot即可

 

实体类配置：

 

@ApiModel

@ApiModelProperty --属性注释， 如

注意： 有时候属性用了注解@ApiModelProperty但未给默认值可能会报错

@ApiModelProperty(value = "设为自增",  example = "1")  //value为注解，exampe为对应属性的默认值
private Integer id; //设为自增

 

Controller配置：

@Api （tags = "") ##不建议去使用

@ApiOperation --放在方法上，用于注释方法

@ApiParams --注释方法参数

 

总结：

可以通过swagger给一些比较难以理解的属性或者方法加一些注解

接口文档实时更新

可以在线测试

注意：出于安全考虑，在项目正式发布的时候，需要关闭swagger,且可以节省内存 --即上面所讲的判断当前的项目环境即可