1. swagger简介

前后端分离时代:
前端 -> 前端控制层,前端视图层
后端 -> 后端控制层,服务处,数据接入层
前后端通过API进行交互,可以使得程序独立且松耦合

  1. swagger是什么?

swagger是一款让你更好的书写API文档的规范且完整的框架,提供了描述生产,消费和可视化的RESTful 风格编程,是由庞大的工具集合支撑的形式化规范,这个集合涵盖了从终端用户接口,底层代码到商业的API管理层面!

  1. 为什么要用swagger

swagger为前端和后端程序员提供了更为规范的API文档,减少在开发过程的各自产生的分歧!

  1. 使用swagger有什么好处?
  • 世界上最流行的API框架
  • RESTful API文档在线自动生成器
  • API文档和API定义同步更新
  • 直接运行,可以在线测试API
  • 支持多种语言,Java,C#,PHP等

2. 新建一个基于web的spring boot项目


测试最基本的环境:

编写controller

@RestController
@RequestMapping("hello")
public class HelloController {
   

    @RequestMapping("sayHello")
    public String sayHello(){
   
        return "Hello Swagger";
    }
}

访问:http://localhost:8080/hello/sayHello

环境搭建完成!

3. 导入swagger依赖

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

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

4. 自定义swagger-ui

@Configuration
@EnableSwagger2
public class SwaggerConfig {
   

    //配置swagger的docket实例
    @Bean
    public Docket docket(){
   
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo());
    }

    private ApiInfo getApiInfo(){
   
        Contact contact = new Contact("liuzeyu12a",
                "https://me.csdn.net/blog/JAYU_37",
                "515801535@qq.com");
        //没有set方法,所以只能通过构造器
        return new ApiInfo("liuzeyu12a`Blog",
                "即使再小的帆也能远航",
                "1.0",
                "https://me.csdn.net/blog/JAYU_37",
                contact, "Apache 2.0",
                "http://apche.org/licenses/LISCENSE-2.0",
                new ArrayList<>());
    }



}

5. 配置扫描接口


WithMethodAnnotation(GetMapping.class):表示只扫描方法上加了GetMapping的get请求
WithClassAnnotation(Controller.class):表示只扫描类上加上了@Controller的接口

除此之外还可以配置接口扫描过滤

实例:


    //配置swagger的docket实例
    @Bean
    public Docket docket(){
   
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(getApiInfo()).
                select().  //select配置扫描的接口
                apis(RequestHandlerSelectors.basePackage("com.liuzeyu.controller")).
                paths(PathSelectors.ant("/haha/**")).  //扫描controller包下haha包下的接口
                build();
    }

接口的扫描位置在com.liuzeyu.controller包下的/haha下的任意接口!
此时写了一个控制类:

swagger界面:

6. 配置swagger开关

如果有一个需求,让swagger在生产环境下使用!

准备多生产环境

swagger配置:

    //配置swagger的docket实例
    @Bean
    public Docket docket(Environment environment){
   
        Profiles profiles = Profiles.of("dev","test");
        boolean flag = environment.acceptsProfiles(profiles);
        System.out.println(flag);
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(getApiInfo()).
                enable(flag).
                select().  //select配置扫描的接口
                apis(RequestHandlerSelectors.basePackage("com.liuzeyu.controller")).
                paths(PathSelectors.ant("/haha/**")).  //扫描controller包下haha包下的接口
                build();
    }

生产环境下可以正常使用swagger

如果注释掉# spring.profiles.active=dev

则关闭swagger

7. 配置API分组

一个分组对应这个一个Docket实例。所有如果需要多个分组,我们应当在容器中注入多个Docket实例。

    //配置swagger的docket实例
    //分组:liuzeyu
    @Bean
    public Docket docket(Environment environment){
   
        Profiles profiles = Profiles.of("dev","test");
        boolean flag = environment.acceptsProfiles(profiles);
        System.out.println(flag);
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(getApiInfo()).
                enable(flag).
                groupName("liuzeyu").
                select().  //select配置扫描的接口
                apis(RequestHandlerSelectors.basePackage("com.liuzeyu.controller")).
                paths(PathSelectors.ant("/haha/**")).  //扫描controller包下haha包下的接口
                build();
    }
    @Bean
    public Docket docket_A(){
   
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket_B(){
   
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }

实际开发中,不同的分组应当对应着不同的开发人员,这样大项目的接口开发分工就会更加明确!

8. 实体类配置

  1. 准备实体类:
@ApiModel("用户实体类")
public class User {
   
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("用户密码")
    public String password;
}

  1. 提供接口,返回值必须是实体类类型!
    @PostMapping("/user")
    public User getUser(){
   
        return new User();
    }
  1. 启动swagger

9. 常用注解

运用在实体类上的注解有
@ApiModel :为实体类添加注释
@ApiModelProperty:为实体类属性添加注释
io.swagger.annotations下,还有一些常用的注解:

swagger注解 简单说明
@Api(tag=“xxxx模块说明”) 作用在类上
@ApiOperation(“xxx接口说明”) 作用在接口方法上
@ApiParam(“xxx”) 作用在j接口方法的字段上

主要目的就是为了生成友好的接口文档,让人跟容易阅读!

10. 小结

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

参考:https://www.bilibili.com/video/BV1PE411i7CV?p=50