Swagger UI简介

Swagger UI 简介

Swagger UI允许任何人（无论您是开发团队还是最终用户）都可以可视化API资源并与之交互，而无需任何实现逻辑。它是根据您的OpenAPI（以前称为Swagger）规范自动生成的，具有可视化文档，可简化后端实现和客户端使用。

SwaggerUI 特点

• 无依赖 UI可以在任何开发环境中使用，无论是本地还是在Web端中。
• 人性化 允许最终开发人员轻松地进行交互，并尝试API公开的每个操作，以方便使用。
• 易于浏览 归类整齐的文档可快速查找并使用资源和端点。
• 所有浏览器支持 Swagger UI 在所有主要浏览器中均可使用，以适应各种可能的情况。
• 完全可定制 通过完整的源代码访问方式以所需方式设置和调整Swagger UI。
• 完整的OAS支持 可视化Swagger 2.0或OAS 3.0中定义的API。

前后端分离

前后端分离时代：

• 后端：后端控制层、服务层、数据访问层 【后端团队】
• 前端：前端控制层、视图层 【前端团队】
  • 伪造后端数据，json。在后端开发前数据以及存在，不需要后端，前端工程师依旧能将项目跑起来。
• 前后端如何交互？ ==>API
• 前后端相对独立，松耦合；
• 前后端甚至可以部署在不同的服务器上。

产生一个问题

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

解决方案：

• 首先指定schema[计划的提纲]，实时更新最新的API，降低集成的风险。
• 早些年，制定Word计划文档
• 前后端分离：
  • 前端测试后端接口使用：Postman工具。
  • 后端提供接口：需要实时更新最新改动和消息。

Swagger登场

• 号称世界上最流行的API框架。
• Restful API文档在线自动生成工具 API文档与API定义同步更新。
• 直接运行，可以在线测试API接口。
• 支持多种语言 如：Java 、PHP…

官网

https://swagger.io/

在项目只能使用SwaggerUI

需要使用Springfox,配置的组件有

• Swagger 2
• UI 显示页面

springboot集成Swagger

 
       dependency> <groupId>io.springfox 
        groupId> <artifactId>springfox-swagger-ui 
         artifactId> <version>2.9.2 
          version>  
           dependency> <dependency> <groupId>io.springfox 
            groupId> <artifactId>springfox-swagger2 
             artifactId> <version>2.9.2 
              version>  
               dependency> 在这里插入代码片 

• 新建一个名为config的Package包
• 创建SwaggerConfig配置类
• @Configuration 表明这是一个配置类
• @EnableSwagger2 开启Swagger2

 @Configuration @EnableSwagger2 //开启swagger2 public class SwaggerConfig { 
      } 

Swagger配置扫描接口

• 配置接口扫描与作者信息
  使用Dokcet对象中的 .select()方法
  
  

/ * 配置了Swagger 的Docket的bean实例,扫描接口的位置 * .apis * RequestHandlerSelectors 配置swagger扫描接口的方式 * basePackage() 指定要扫描哪些包 * any() 全部都扫描 * none() 全部不扫描 * withClassAnnotation() 扫描类上的注解 参数是一个注解的反射对象 * withMethodAnnotation() 扫描包上的注解 * .paths * PathSelectors 路径扫描接口 * ant 配置以xxx 开头的路径 * @return */ @Bean public Docket docket( ){ 
      return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("James") .select() .apis(RequestHandlerSelectors.basePackage("com.study.swagger.controller")) //.paths(PathSelectors.ant("/hello/")) .build();//构建者模式 } /** * 配置Swagger信息 apiinfo * @return */ private ApiInfo apiInfo(){ 
      //配置作者信息 Contact DEFAULT_CONTACT = new Contact("James", "https://blog.csdn.net/zhanshixiang/", ""); return new ApiInfo( "James 的Swagger API文档", "码出高效", "v1.0", "https://blog.csdn.net/zhanshixiang/", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } 

配置是否自动启动Swagger

在开发环境开启SwaggerUI ，生产环境关闭SwaggerUI 是因为开发环境是内部人员，生产环境是客户。为了程序的安全性需要关闭SwagggerUI

/ * 配置了Swagger 的Docket的bean实例,扫描接口的位置 * .apis * RequestHandlerSelectors 配置swagger扫描接口的方式 * basePackage() 指定要扫描哪些包 * any() 全部都扫描 * none() 全部不扫描 * withClassAnnotation() 扫描类上的注解 参数是一个注解的反射对象 * withMethodAnnotation() 扫描包上的注解 * .paths * PathSelectors 路径扫描接口 * ant 配置以xxx 开头的路径 * @return */ @Bean public Docket docket(Environment environment){ 
      //设置要显示的Swagger 环境 Profiles profiles =Profiles.of("dev","test"); / * 通过 environment.acceptsProfiles 返回的boolean值判断是否处在自己所设定的环境中 */ boolean flag = environment.acceptsProfiles(profiles); System.out.println(flag); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("James") //.enable(flag) //enable配置是否自动启动swagger 如果为False则为不启动，浏览器中不能访问Swagger .select() .apis(RequestHandlerSelectors.basePackage("com.study.swagger.controller")) //.paths(PathSelectors.ant("/hello/")) .build();//构建者模式 } /** * 配置Swagger信息 apiinfo * @return */ private ApiInfo apiInfo(){ 
      //配置作者信息 Contact DEFAULT_CONTACT = new Contact("James", "https://blog.csdn.net/zhanshixiang/", ""); return new ApiInfo( "James 的Swagger API文档", "码出高效", "v1.0", "https://blog.csdn.net/zhanshixiang/", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } 

• 创建三个properties文件
  application.properties
  
  

# 激活开发环境 spring.profiles.active=dev 

application-dev.properties 开发环境

server.port=8082 

application-properties 生产环境

server.port=8083 

配置API分组

在协同开发时，每个开发人员都拥有一个属于自己的API组

.groupName("test") 

问题：如何配置多个分组？

编写多个Docket 设置不同Docket方法名

/ * 开发A组的接口 * @return */ @Bean public Docket docketA(){ 
      return new Docket(DocumentationType.SWAGGER_2) .groupName("A"); } / * 开发B组的接口 * @return */ @Bean public Docket docketB(){ 
      return new Docket(DocumentationType.SWAGGER_2) .groupName("B"); } / * 开发C组的接口 * @return */ @Bean public Docket docketC(){ 
      return new Docket(DocumentationType.SWAGGER_2) .groupName("C"); } 

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

配置实体类信息

@ApiModel("用户实体类") public class User implements Serializable { 
      @ApiModelProperty("用户名") private String username; @ApiModelProperty("密码") private String password; 

配置接口方法

@Api("Hello控制类") @RestController @RequestMapping("hello") public class HelloController { 
      @GetMapping(value = "say") public String hello() { 
      return "hello "; } / * 只要接口中,返回值中存在实体类，他就会被扫描到Swagger中 * @return */ @PostMapping(value = "/user") public User user(){ 
      return new User(); } / * ApiOperation接口，不是放在类上的，是方法 * @return */ @ApiOperation("hello控制类") @GetMapping(value = "/hello2") public String hello2(@ApiParam("用户名") String username){ 
      return "hello"+username; } @ApiOperation("Post测试类") @PostMapping(value = "/post") public User post(@ApiParam("用户") User user){ 
      return user; } }