SpringBoot+Swagger2集成详细说明

引言：

为什么使用Swagger？

在Vue没有出来之前，都是前后端在一起：

• 后端用的SSM或者SSH框架

• 前端完全就是静态页面+模板引擎。例如：JSP开发久的人应该听说过，和现在的Thymeleaf、 Velocity、FreeMarker 类似

在Vue出来之后，进入真正的前后端分离时代：

• 后端依然可以是SSM架构，而现在大厂都在使用微服务SpringBoot、SpringCloud等

• 前端就独立出来了，只管呈现效果也就是是三层架构的视图层

为什么叫前后端分离呢？

分离就是各自开发自己的，互不干扰

优点：

• 前端可以不用等后端人员开发完在测试，直接就可以使用Json伪造数据测试，例如：JsonServer工具

• 可以部署在不同的服务器上

• 有新的项目可以随时拆分模块

缺点：

• 此时就需要在招专业开发前端的人员，这就是老板的事了。。。

Swagger简介：

Swagger是一个流行的API开发框架，Swagger容许用户使用Swagger编辑器描述OAS 3.0API，并使用SwaggerUI可视化并自动生成OAS 3.0中定义的API文档。

Swagger可以对整个API开发周期提供一个完整框架，解决调试过程中的各种问题，包括API设计，开发，测试，完档，并且几乎支持所有语言。

Swagger的用途来了：

问题：

前后端分离联调，前后端人员无法做到及时的调试？

当年的解决方案：

• 编写Word文档，及时更新(但是很难做到，一般容易忘记)

• 模拟测试后端接口：postman

• 后端开发完之后，提供接口，根据需求在调整

现在的解决方案：

• Api文档与API定义同步更新

• 直接运行，在线测试后端接口

• 对多种编程语言的支持

SpringBoot集成Swagger：

1.建立SpringBoot-Web项目

2.引入Swagger依赖

Swagger UI：用于展示API规范

Springfox：是一个通过扫描代码提取代码中的信息，生成API文档的工具。API文档的格式不止Swagger的OpenAPI Specification，还有RAML，jsonapi，Springfox的目标同样包括支持这些格式。

 <dependency>    <groupId>io.springfoxgroupId>    <artifactId>springfox-swagger2artifactId>    <version>2.9.2version>dependency><dependency>    <groupId>io.springfoxgroupId>    <artifactId>springfox-swagger-uiartifactId>    <version>2.9.2version>dependency>

3.配置Swagger

 @Configuration@EnableSwagger2 // 开启Swaggerpublic class SwaggerConfig {}

4.编写Controller

 @RestControllerpublic class TestController {    @RequestMapping("hello")    public String hello(){        return "hello swagger2";    }}

6.项目结构

7.启动项目

访问：http://localhost:8080/swagger-ui.html

Swagger配置进阶

Swagger信息和组信息进行配置

 @Configuration@EnableSwagger2 // 开启Swaggerpublic class SwaggerConfig {//    配置Docket的bean实例    @Bean    public Docket docket(Environment environment){        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .enable(true)// enable是否启动Swagger，如果False，则Swagger不能再浏览器中访问                .groupName("yangjun")// 配置API分组                .select()//                RequestHandlerSelectors，配置扫描接口的方式//                basePackage：指定要扫描的包//                any()：扫描全部//                none()：不扫描//                withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象//                withMethodAnnotation：扫描方法上的注解                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))//                paths 过滤路径                //.path(PathSelectors.ant("/example/**"))                .build();    }//    配置Swagger信息=apiInfo    private ApiInfo apiInfo() {//      作者信息        Contact contact = new Contact("作者：XX","作者QQ空间","作者Email");        return new ApiInfo("测试SwaggerApi文档"        ,"好好学习，天天向上",                "V0.1",                "团队文档地址",                contact,                "Apache2.0",                "Apache2.0地址",                new ArrayList<>());    }}

问题来了：

如果我们只在测试环境中使用，而不在生产环境中使用该怎么办？

 enable(true)// enable是否启动Swagger，如果False，则Swagger不能再浏览器中访问

• 判断当前的环境

• 设置enable(true)值

 public Docket docket(Environment environment){    //设置要显示的Swagger环境    Profiles profiles = Profiles.of("dev","test");    //通过environment.acceptsProfiles判断是否处在自己设定的环境当中    boolean flag = environment.acceptsProfiles(profiles);    return new Docket(DocumentationType.SWAGGER_2)        .apiInfo(apiInfo())        .enable(flag)// enable是否启动Swagger，如果False，则Swagger不能再浏览器中访问        .groupName("yangjun")// 配置API分组        .select()        .apis(RequestHandlerSelectors.basePackage("com.example.controller"))        .build();}

配置分组

配置多个实例即可

 @Beanpublic Docket docket1(){return new Docket(DocumentationType.SWAGGER_2).groupName("测试分组1");}@Beanpublic Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName("测试分组2");}

API使用：

涉及到的5个注解

• @Api(tags = "类")：加在类上

• @ApiOperation：加在方法上

• @ApiParam("用户名")：加在参数上

• @ApiModel("用户实体类")：加在实体类上

• @ApiModelProperty("用户名")：加在字段上

1.@Api的使用

在类上使用主要来阐述这个类的作用

 @Api(tags = "TestController测试类")@RestControllerpublic class TestController {    @RequestMapping(value = "/hello",method = RequestMethod.GET)    public String hello(){        return "hello swagger2";    }}

2.@ApiOperation的使用

在方法上使用主要来阐述这方法的用户以及需要传入那些参数和类型

 @Api(tags = "TestController测试类")@RestControllerpublic class TestController {    @RequestMapping(value = "/hello",method = RequestMethod.GET)    public String hello(){        return "hello swagger2";    }    @ApiOperation("测试控制类1")    @PostMapping("/user1")    public String getUser2(@ApiParam("用户名") User user){        return user.toString();    }}

3.@ApiParam的使用

定义用户输入参数的格式，不用在拼接字符串，Swagger会自动配置好，我们只要填入参数测试

 @Api(tags = "TestController测试类")@RestControllerpublic class TestController {    @RequestMapping(value = "/hello",method = RequestMethod.GET)    public String hello(){        return "hello swagger2";    }    @ApiOperation("测试控制类1")    @PostMapping("/user1")    public String getUser2(@ApiParam("用户名") User user){        return user.toString();    }}

4.@ApiModel和@ApiModelProperty的使用

在实体类使用，提供每个字段名和类型，关键可以和MybatisPlus一起使用，只要在数据库中定义好字段的备注，使用MP的代码自动生成就OK了

 @Data@ApiModel("用户实体类")public class User {    @ApiModelProperty("用户名")    private String name;    @ApiModelProperty("用户密码")    private String password;}

总结：

1.在开发过程中对接口更新更快

2.能够快速导出API文档

3.不用第三方工具即可测试接口

完整代码：

https://gitee.com/hahaguai007/springboot-swagger2.git

点亮 ，告诉大家你也在看