Swagger UI 简介


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

在这里插入图片描述

SwaggerUI 特点


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

前后端分离

Vue + SpringBoot
后端时代:前端只用管理静态页面; html==》后端。 模版引擎 JSP=>后端是主力

前后端分离时代:

  • 后端:后端控制层、服务层、数据访问层 【后端团队】
  • 前端:前端控制层、视图层 【前端团队】
    • 伪造后端数据,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

1.idea新建SpringBoot-Web工程
2.POM文件中导入springfox-swagger2和springfox-swagger-ui

</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>
在这里插入代码片

3.编写一个测试Controller 测试SpringBoot工程搭建是否成功。
4.配置Swagger 编写Config文件

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

5 、测试运行
浏览器打开 http://localhost:8080/swagger-ui.html
SwaggerUI 首页

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/", "zhanshixiang1997@163.com");
        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/", "zhanshixiang1997@163.com");
        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;
    }
    
}

在这里插入图片描述

Logo

基于 Vue 的企业级 UI 组件库和中后台系统解决方案,为数万开发者服务。

更多推荐