Swagger使用

Swagger

1.简介

  • 了解Swagger的作用和概念
  • 了解前后端分离
  • 在springboot中集成Swagger

前后端分离

  • vue+springboot
  • 前端---前端控制层、视图层
  • 后端---后端控制层、服务层、数据层
  • 前后端通过API进行交互

产生的问题

  • 前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方法

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

swagger诞生

  • 号称世界上最流行的Api框架
  • Restful Api 文档在线自动生成器
  • 直接运行，在线测试API
  • 支持多种语言 （如：Java，PHP等）
  • 官网：https://swagger.io/

2.swagger的使用

SpringBoot集成Swagger => springfox，两个jar包

  • Springfox-swagger2
  • swagger-springmvc

使用步骤

  1. 新建一个springboot项目

  2. 导入依赖

    <!--Swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!--swagger2-ui-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

  3. 编写controller，测试运行成功

  4. 要使用Swagger，我们需要编写一个配置类-SwaggerConfig来配置 Swagger

    package com.mybatisplus.ant.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

  5. 访问测试：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

3.Swagger的配置

  1. 通过配置Docket实例来配置Swaggger

    @Bean //配置docket以配置Swagger具体参数
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2);
}

  2. 通过apiInfo()属性配置文档信息

    //配置swagger的信息————————》apiInfo
    public ApiInfo apiInfo(){
        Contact contact = new Contact("清歌", "www.baidu.com", "353717996@qq.com");  //作者信息
        return new ApiInfo(
                "清歌的API接口",  //标题
                "前后端分离API管理",  //描述
                "1.1",   //版本
                "",  //地址
                contact,
                "Apacher2.5",
                "",
                new ArrayList()

        );
    }

  3. Docket 实例关联上 apiInfo()

    @Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

  4. 重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果；

4.配置扫描的接口

@Bean
public Docket docket(Environment environment) {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                //RequestHandlerSelectors  配置要扫描接口的方式
                //basePackage 指定要扫描的包  basePackage("com.mabatis")
                //any  扫描所有的
                //none  全部不扫描
                //withClassAnnotation  扫描类上的注解，参数是一个注解的反射对象
                //.withMethodAnnotation  扫描方法上的注解
            	  .apis(RequestHandlerSelectors.basePackage("com.mabatis.ant.controller"))
                //过滤什么路径
                //.paths(PathSelectors.ant("/com/mabatis/**"))
                .build();
    }

5.配置Swagger开关

  1. 通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

    @Bean
public Docket docket(Environment environment) {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
            	.enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
            	.apis(RequestHandlerSelectors.basePackage("com.mabatis.ant.controller"))
                .build();
    }

  2. 动态配置当项目处于dev环境时显示swagger，处于prod时不显示

    @Bean
public Docket docket(Environment environment) {
   // 设置要显示swagger的环境
   Profiles profiles = Profiles.of("dev");
   // 判断当前是否处于该环境
   // 通过 enable() 接收此参数判断是否要显示
   boolean flag = environment.acceptsProfiles(profiles);
   
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(flag) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.mabatis.ant.controller"))
      .build();
}

  3. 测试效果

6.配置API分组

  1. 如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

    @Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("清歌") // 配置分组
}

  2. 重启测试

  3. 配置多个分组

    @Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

  4. 重启测试

7.实体配置

  1. 新建实体类

    @Data
@EqualsAndHashCode(callSuper = false)
@ApiModel(value="BookInfo对象", description="")
public class BookInfo implements Serializable {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "图书id")
    @TableId(value = "book_id", type = IdType.AUTO)
    private Long bookId;

    @ApiModelProperty(value = "书名")
    private String name;

    @ApiModelProperty(value = "作者")
    private String author;

    @ApiModelProperty(value = "出版社")
    private String publish;

    @ApiModelProperty(value = "ISBN")
    @TableField("ISBN")
    private String isbn;

    @ApiModelProperty(value = "简介")
    private String introduction;

    @ApiModelProperty(value = "语言")
    private String language;

    @ApiModelProperty(value = "价格")
    private BigDecimal price;

    @ApiModelProperty(value = "出版日期")
    private Date pubdate;

    @ApiModelProperty(value = "分类号")
    private Integer classId;

    @ApiModelProperty(value = "书架号")
    private Integer pressmark;

    @ApiModelProperty(value = "状态")
    private Integer state;

    @ApiModelProperty(value = "逻辑删除")
    @TableLogic
    private Integer deleted;

    @ApiModelProperty(value = "乐观锁")
    @Version
    private Integer version;

    @ApiModelProperty(value = "创建时间")
    @TableField(fill = FieldFill.INSERT)
    private Date createTime;

    @ApiModelProperty(value = "修改时间")
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private Date updateTime;
}

  2. 只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

    @ApiOperation("书籍信息")
    @PostMapping("/books")
    public BookInfo bookInfo(){
        return new BookInfo();
    }

  3. 测试效果

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：

posted @ 2021-05-10 12:40  神佑我阿羡  阅读(95)  评论(0)    收藏  举报