Swagger----Springboot集成Swagger

前言

说起Swagger就不得不说前后端分离

当前最主流的前后端分离技术栈：Vue+Springboot

后端时代：

前端只用管理静态页面:html

最后统一交给后端，后端将其修改为jsp，在整个过程中，后端充当主力

前后端分离时代：

后端：后端控制层，服务层，数据访问层【后端团队】

前端：前端控制层，视图层【前端团队】

前端可以自定义一些伪后端数据：json,在写的时候就存在，不需要后端，前端工程依旧能够跑起来

那么前端后端如何交互？
此时我们可以考虑API

前后端分离好处：

• 前后端相对独立，松耦合
• 前后端设置可以部署在不同的服务器上

产生的问题：

• 前后弹集成联调，前端人员和后端人员无法做到及时协商，尽早解决，最终导致问题爆发；

解决方式：

• 首先指定schema[计划的提纲]，实时更新最新的API，降低集成风险
• 早期：指定word计划文档
• 前后端分离时期：

前端测试后端接口：postman

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

在项目当中使用Swagger需要springbox；

• swagger2
• ui

一、Swagger

• 号称世界上最流行的Api框架
• RestFul Api 文档在线自动生成工具，Api文档与Api定义同步更新
• 直接运行，可以在线测试API接口
• 支持多种语言：（Java,php等）

官网地址：http://swagger.io/

二、SpringBoot集成Swagger

1.新建一个SpringBoot = web项目

2.导入依赖

<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>

3.集成Swagger ==>Config

@EnableSwagger2 用来开启Swagger2

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

}

4.进入测试

http://localhost:8080/swagger-ui.html

配置Swagger

# 配置Swagger基本信息 Swagger的Bean实例Docket:

package com.fwp.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
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
public class SwaggerConfig {
    //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors配置要扫描接口的方式
                //basePackage指定要扫描的包
                //any() 扫描全部
                //none() 都不扫描
                //withClassAnnotation() 扫描类上的注解,参数是一个注解的反射对象
                //withMethodAnnotation() 扫描上的注解,参数是一个注解的反射对象
                .apis(RequestHandlerSelectors.basePackage("com/fwp/swagger/controller"))
                .paths(PathSelectors.ant("/fwp/**"))
                .build();
    }
    //配置Swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("鹏鹏", "https://blog.csdn.net/weixin_51132678?type=blog", "3230609771@qq.com");

        return new ApiInfo(
                "鹏鹏的SwaggerAPI文档",
                "即使再小的船也能上岸",
                "1.0",
                "https://blog.csdn.net/weixin_51132678?type=blog",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

三、Swagger配置扫描接口

Docket.select()

//配置了Swagger的Docket的Bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors配置要扫描接口的方式
            //basePackage指定要扫描的包
            //any() 扫描全部
            //none() 都不扫描
            //withClassAnnotation() 扫描类上的注解,参数是一个注解的反射对象
            //withMethodAnnotation() 扫描方法上的注解,参数是一个注解的反射对象
            .apis(RequestHandlerSelectors.basePackage("com.fwp.swagger.controller"))
            //过滤
            .paths(PathSelectors.ant("/fwp/**"))
            .build();
}

配置是否启动swagger

enable是否启动swagger。如果为false，则swagger在浏览器中不能访问

 //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)

swagger启动失败

那么如果我们希望Swagger在某一个环境中使用，在其他时候不使用怎么办

dev环境下：

server.port=8081

pro环境下：

server.port=8082

application.properties文件

spring.profiles.active=dev

此时我们处于dev环境下，我们希望swagger在dev环境下能使用，在其他环境下不能使用

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
    //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境  可返回多个
        Profiles profiles = Profiles.of("dev","test");
        //获取生产环境
        //通过environment.acceptsProfiles(profiles)判断自己是否处在指定环境
        boolean flag = environment.acceptsProfiles(profiles);
        System.out.println(flag);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//enable是否启动swagger。如果为false，则swagger在浏览器中不能访问
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.fwp.swagger.controller"))
                //过滤
                //.paths(PathSelectors.ant("/fwp/**"))
                .build();
    }
    //配置Swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("鹏鹏", "https://blog.csdn.net/weixin_51132678?type=blog", "3230609771@qq.com");

        return new ApiInfo(
                "鹏鹏的SwaggerAPI文档",
                "即使再小的船也能上岸",
                "1.0",
                "https://blog.csdn.net/weixin_51132678?type=blog",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

将enable()中的参数值设置为flag，这样当我们处于dev与test环境下时swagger默认开启，其他情况下默认关闭
进入dev环境

进入pro环境

四、配置API文档分组

return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .groupName("鹏鹏")

如果我们想配置多个分组怎么办呢？
创建多个docket对象，设置不同的组名

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

可以看见页面中出现了不同的组别，每个组别之间互不干扰，利于合作开发，每个人扫描自己的包，做自己的事情

五、实体类的配置

User类

@Data
@AllArgsConstructor
@NoArgsConstructor

//@Api("注释")
@ApiModel("用户实体类")
public class User {


    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

HelloController中：

//只要返回值中存在实体类，他就会被扫描到Swagger中
@PostMapping("/user")
public User user(){
    return new User("pp","123");
}

文档注解

为了方便交互，方便文档阅读，我们可以为文档添加说明信息

• @ApiModel(“用户实体类”)为实体类添加说明信息

• @ApiModelProperty(“用户名”)为实体类中的属性添加说明信息

• @Api(tags = “控制器-hello”)为接口添加说明信息

• @ApiOperation(“hello请求”)为请求增加说明信息

• @ApiParam(“hello请求中的name”)为请求中的参数增加说明信息

实体类

@Data
@AllArgsConstructor
@NoArgsConstructor

//@Api("注释")
@ApiModel("用户实体类")
public class User {


    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

HelloController:

@RestController
public class HelloController {

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

    //只要返回值中存在实体类，他就会被扫描到Swagger中
    @PostMapping("/user")
    public User user(){
        return new User("pp","123");
    }


    //Operation接口   放在方法上而不是类上
    @ApiOperation("Hello控制类")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return "hello!!!"+username;
    }

添加注释后展示：

总结

1. 我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息
2. 接口文档实时更新
3. 可以在线测试

注意点：
在正式发布的时候，需要关闭Swagger，一是出于安全考虑，，二是节省内存