JavaEE_Swagger

1.学习目标
了解Swagger的作用和概念
了解前后端分离
在SpringBoot中集成Swagger
2.Swagger简介
前后端分离：
Vue + SpringBoot
后端时代：前端只用管理静态页面；html->后端，模板引擎 JSP->后端是主力。
前后端分离时代：
后端：后端控制层，服务层，数据访问层【后端团队】。
前端：前端控制层，视图层【前端团队】
前端后端如何交互：----> JSP
前后端相对独立，松耦合。
前后端甚至可以部署在不同的服务器上。

产生一个问题：
前后端集成联调，前端人员和后端人员无法做到“即使协商，尽早解决”，最终导致问题集中爆发。
解决方案：
首先指定schema计划的提纲，实时更新API，降低集成的风险；
早些年，指定word文档。
前后端分离：
前端测试后端接口：postman
后端提供接口，需要实时更新最新的消息及改动。

Swagger
号称世界上最流行的API框架；
RestFul API文档在线生成工具—>API文档与API定义同步更新；
直接运行，可以在线调试API接口；
支持多种于语言：(Java、Php)

官网：
在项目中使用Swagger需要Springbox：
Swagger2
ui

SprongBoot集成Swagger
1.新建一个SpringBoot项目：
2.导入依赖

 <!-- 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.编写一个Hello工程
4.配置Swager--->Config


@Configuration //等价于component
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {}

5.测试运行：http://localhost:8989/swagger-ui.html
测试图如下：

配置Swager
Swagger的Bean实例Docket：

package com.kuang.swagger.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 //等价于component
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {// 配置了Swager的Docket的Bean实例@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());}// 配置Swagger信息 = apiInfoprivate ApiInfo apiInfo(){// 作者信息Contact contact = new Contact("马炳阳", "https:", "957935694@qq.comn");return new ApiInfo("maby的swagger文档","maby很酷","1.0","http://",contact,"Apache2.0","www",new ArrayList<>());}
}

Swagger配置扫描接口
Docket.select()

package com.kuang.swagger.config;import com.kuang.swagger.controller.HelloController;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Controller;
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 //等价于component
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {// 配置了Swager的Docket的Bean实例@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// basePackage指定要扫描的包 生成对应的api接口// any() 扫描全部// none() 不扫描// withClassAnnotation 扫描类上的注解 参数是一个注解的反射对象 一般应basePackage.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))//.apis(RequestHandlerSelectors.withClassAnnotation(.class))// paths 过滤路径.paths(PathSelectors.ant("/kuang/**")) // 扫描kuang下面的接口.build(); // 工厂模式}// 配置Swagger信息 = apiInfoprivate ApiInfo apiInfo(){// 作者信息Contact contact = new Contact("马炳阳", "https:", "957935694@qq.comn");return new ApiInfo("maby的swagger文档","maby很酷","1.0","http://",contact,"Apache2.0","www",new ArrayList<>());}
}

配置是否启动Swagger

package com.kuang.swagger.config;import com.kuang.swagger.controller.HelloController;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Controller;
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 //等价于component
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {// 配置了Swager的Docket的Bean实例@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(false) // 是否启用Swagger false swagger不能在浏览器中访问.select()// basePackage指定要扫描的包 生成对应的api接口// any() 扫描全部// none() 不扫描// withClassAnnotation 扫描类上的注解 参数是一个注解的反射对象 一般应basePackage.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))//.apis(RequestHandlerSelectors.withClassAnnotation(.class))// paths 过滤路径//.paths(PathSelectors.ant("/kuang/**")).build(); // 工厂模式}// 配置Swagger信息 = apiInfoprivate ApiInfo apiInfo(){// 作者信息Contact contact = new Contact("马炳阳", "https:", "957935694@qq.comn");return new ApiInfo("maby的swagger文档","maby很酷","1.0","http://",contact,"Apache2.0","www",new ArrayList<>());}
}

判断是不是生产环境：

server:port: 8989
spring:profiles:active: dev

server:port: 8990

server:port: 8991

package com.kuang.swagger.config;import org.springframework.context.annotation.Bean;
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 //等价于component
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {// 配置了Swagger的Docket的Bean实例@Beanpublic Docket docket(Environment environment){// 设置要显示的Swagger环境Profiles profiles = Profiles.of("dev","test"); // 返回目前的Profiles// 获取项目的环境：// 通过 environment.acceptsProfiles(profiles);判断是否处在自己设定的环境中boolean acceptsProfiles = environment.acceptsProfiles(profiles);return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(acceptsProfiles) // 是否启用Swagger false swagger不能在浏览器中访问.select()// basePackage指定要扫描的包 生成对应的api接口// any() 扫描全部// none() 不扫描// withClassAnnotation 扫描类上的注解 参数是一个注解的反射对象 一般应basePackage.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))//.apis(RequestHandlerSelectors.withClassAnnotation(.class))// paths 过滤路径//.paths(PathSelectors.ant("/kuang/**")).build(); // 工厂模式}// 配置Swagger信息 = apiInfoprivate ApiInfo apiInfo(){// 作者信息Contact contact = new Contact("马炳阳", "https:", "957935694@qq.comn");return new ApiInfo("maby的swagger文档","maby很酷","1.0","http://",contact,"Apache2.0","www",new ArrayList<>());}
}

配置API文档的分组：

package com.kuang.swagger.config;import org.springframework.context.annotation.Bean;
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 // 等价于component
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {// 配置了Swagger的Docket的Bean实例@Beanpublic Docket docket(Environment environment){// 设置要显示的Swagger环境Profiles profiles = Profiles.of("dev","test"); // 返回目前的Profiles// 获取项目的环境：// 通过 environment.acceptsProfiles(profiles);判断是否处在自己设定的环境中boolean acceptsProfiles = environment.acceptsProfiles(profiles);return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("马炳阳").enable(acceptsProfiles) // 是否启用Swagger false swagger不能在浏览器中访问.select()// basePackage指定要扫描的包 生成对应的api接口// any() 扫描全部// none() 不扫描// withClassAnnotation 扫描类上的注解 参数是一个注解的反射对象 一般应basePackage.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))//.apis(RequestHandlerSelectors.withClassAnnotation(.class))// paths 过滤路径//.paths(PathSelectors.ant("/kuang/**")).build(); // 工厂模式}// 配置Swagger信息 = apiInfoprivate ApiInfo apiInfo(){// 作者信息Contact contact = new Contact("马炳阳", "https:", "957935694@qq.comn");return new ApiInfo("maby的swagger文档","maby很酷","1.0","http://",contact,"Apache2.0","www",new ArrayList<>());}
}

如何配置多个分组：
.groupName(“马炳阳”)与Docket相关。

@Beanpublic Docket docket1(){return new Docket(DocumentationType.SWAGGER_2).groupName("A");}@Beanpublic Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName("A");}@Beanpublic Docket docket3(){return new Docket(DocumentationType.SWAGGER_2).groupName("A");}org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.IllegalStateException: Multiple Dockets with the same group name are not supported. The following duplicate groups were discovered. A

package com.kuang.swagger.pojo;public class User {public String username;public String password;
}

package com.kuang.swagger.controller;import com.kuang.swagger.pojo.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;@RestController![在这里插入图片描述](https://img-blog.csdnimg.cn/20200226132238951.PNG?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwODI4NzA1,size_16,color_FFFFFF,t_70)
public class HelloController {@GetMapping("/hello")public String hello(){return "hello";}// 只要我们的接口中，返回值存在实体类，他就会被扫描到Swagger@PostMapping(value = "/user")public User user(){return new User();}}

package com.kuang.swagger.pojo;import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;@ApiModel("用户实体类")
public class User {@ApiModelProperty("用户名")public String username;@ApiModelProperty("密码")public String password;
}

package com.kuang.swagger.controller;import com.kuang.swagger.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;// @Api("Hellokongzhilei") 此处无用
@RestController
public class HelloController {@GetMapping("/hello")public String hello(){return "hello";}// 只要我们的接口中，返回值存在实体类，他就会被扫描到Swagger@PostMapping(value = "/user")public User user(){return new User();}@ApiOperation("Hello控制类") // 不是放在类上的@GetMapping(value = "/hello2")public String hello(@ApiParam("用户名") String username){return "hello2" + username;}@ApiOperation("Post测试类") // 不是放在类上的@PostMapping(value = "/postt")public User postt(@ApiParam("用户名") User user){int i = 5 / 0;user = new User("maby0","000000");return  user;}
}

总结：
1.我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息。
2.接口文档实时更新。
3.可以在线调试。
Swagger是一个优秀的工具，几乎所有的大公司都有使用它。
【注意点】在正是发布时，关闭Swagger！！！处于安全考虑，而且节省运行的内存。

JavaEE_Swagger

JavaEE_Swagger相关推荐

最新文章

热门文章