swagger使用指引

1.swagger介绍

在前后端分离开发中通常由后端程序员设计接口，完成后需要编写接口文档，最后将文档交给前端工程师，前端工程师参考文档进行开发。

可以通过一些工具快速生成接口文档 ，本项目通过Swagger生成接口在线文档 。

什么是Swagger？

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。

（GitHub - OAI/OpenAPI-Specification: The OpenAPI Specification Repository）

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，Swagger是一个在线接口文档的生成工具，前后端开发人员依据接口文档进行开发。 (API Documentation & Design Tools for Teams | Swagger)

Spring Boot 可以集成Swagger，Swaager根据Controller类中的注解生成接口文档 ，只要添加Swagger的依赖和配置信息即可使用它。

2.引入swagger依赖

在api模块中,引入springboot集成swagger的依赖

        <!--springboot集成swagger-->
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
        </dependency>


<!--swagger的版本,如果使用父模块管理是如下格式,也可以在本模块<version/>标签标注-->
 <swagger-spring-boot-starter.version>1.9.0.RELEASE</swagger-spring-boot-starter.version>

3.添加swagger配置

在bootstrap.yml配置文件中(也可能是application.yml),引入swagger配置;

其中base-package为扫描的包路径,扫描Controller类.

swagger:
  title: "整个项目的名称或标志"
  #定制包扫描路径。配置包扫描路径
  description: "内容系统管理系统对课程相关信息进行管理"
  base-package: com.xuecheng.content
  enabled: true
  version: 1.0.0

4.在启动类中添加@EnableSwagger2Doc注解

再次启动服务，工程启动起来，访问http://localhost:8800/content/swagger-ui.html查看接口信息,其中8800为项目端口号,localhost代表本机,可根据实际情况修改,后面的信息swagger-ui.html为固定信息.

5.添加接口说明注解

可以方便查看接口说明

并将定义在方法上的@RestMapping修改位对应的@Postmapping等.

添加完注解后可以方便阅读接口文档,特别是接口文档较多的情况下,提高开发效率

 @Api(value = "课程信息编辑接口",tags = "课程信息编辑接口")
 @RestController
public class CourseBaseInfoController {

  @ApiOperation("课程查询接口")
 @PostMapping("/course/list")
  public PageResult<CourseBase> list(PageParams pageParams, @RequestBody(required=false) QueryCourseParamsDto queryCourseParams){
     //....
  }
}

6.添加模型类中的属性说明注解

接口文档中会有关于接口参数的说明,在模型类上也可以添加 注解对模型类中的属性进行说明,方便对接口文档的阅读

public class PageParams {
 ...
     @ApiModelProperty("当前页码")
    private Long pageNo = 1L;

    @ApiModelProperty("每页记录数默认值")
    private Long pageSize = 30L;
...
public class QueryCourseParamsDto {

      //审核状态
    @ApiModelProperty("审核状态")
     private String auditStatus;
     //课程名称
     @ApiModelProperty("课程名称")
     private String courseName;

}

7.Swaager的常用注解如下：

在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：

 8.测试

使用Swagger可以进行接口的测试。

修改接口内容，添加一些测试代码

@ApiOperation("课程查询接口")
@PostMapping("/course/list")
public PageResult<CourseBase> list(PageParams pageParams, @RequestBody(required=false) QueryCourseParamsDto queryCourseParams){

    CourseBase courseBase = new CourseBase();
    courseBase.setName("测试名称");
    courseBase.setCreateDate(LocalDateTime.now());
    List<CourseBase> courseBases = new ArrayList();
    courseBases.add(courseBase);
    PageResult pageResult = new PageResult<CourseBase>(courseBases,10,1,10);
    return pageResult;

}

9.时间格式转换

存在一个问题就是LocalDateTime类型的数据转json后数据格式并不是我们要的年月日时分秒,提供两种方法:

9.1 使用@JsonFormat注解

先引入对应的依赖

        <!--JsonFormat-->
 
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
            <version>2.8.8</version>
        </dependency>
 
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.8.8</version>
        </dependency>
 
        <dependency>
            <groupId>org.codehaus.jackson</groupId>
            <artifactId>jackson-mapper-asl</artifactId>
            <version>1.9.13</version>
        </dependency>

不过在springboot-starter-web中有相应的前两个依赖 

将注解添加到需要转换时间格式的相应字段上,并在pattern属性中设置需要的时间格式

    @ApiModelProperty(value = "创建时间")
    @TableField("create_date")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss",timezone = "GMT+8")
    private LocalDateTime createDate;

 这里解释一下：@JsonFormat(pattern="yyyy-MM-dd",timezone = "GMT+8")

   pattern:是你需要转换的时间日期的格式

   timezone：是时间设置为东八区，避免时间在转换中有误差

  提示：@JsonFormat注解可以在属性的上方，同样可以在属性对应的get方法上，两种方式没有区别

完成上面两步之后，我们用对应的实体类来接收数据库查询出来的结果时就完成了时间格式的转换，再返回给前端时就是一个符合我们设置的时间格式了

@DateTimeFormat的使用和@jsonFormat差不多，首先需要引入是spring还有jodatime依赖

  <!-- joda-time -->
        <dependency>
            <groupId>joda-time</groupId>
            <artifactId>joda-time</artifactId>
            <version>2.3</version>
        </dependency>

在controller层我们使用spring mvc 表单自动封装映射对象时，我们在对应的接收前台数据的对象的属性上加@DateTimeFormat 

 
 
    @DateTimeFormat(pattern = "yyyy-MM-dd")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss",timezone="GMT+8")
    private Date symstarttime;
 
    @DateTimeFormat(pattern = "yyyy-MM-dd")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss",timezone="GMT+8")
    private Date symendtime;

总结： 

  注解@JsonFormat主要是后台到前台的时间格式的转换

  注解@DateTimeFormat 主要是前后到后台的时间格式的转换

9.2 通过添加配置文件实现时间格式转换

因为这个文件可以通用,建议设置在父类工程中,config/LocalDateTimeConfig文件中:

import com.fasterxml.jackson.datatype.jsr310.deser.LocalDateTimeDeserializer;
import com.fasterxml.jackson.datatype.jsr310.ser.LocalDateTimeSerializer;
import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

@Configuration
public class LocalDateTimeConfig {

    /*
     * 序列化内容
     *   LocalDateTime -> String
     * 服务端返回给客户端内容
     * */
    @Bean
    public LocalDateTimeSerializer localDateTimeSerializer() {
        return new LocalDateTimeSerializer(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
    }

    /*
     * 反序列化内容
     *   String -> LocalDateTime
     * 客户端传入服务端数据
     * */
    @Bean
    public LocalDateTimeDeserializer localDateTimeDeserializer() {
        return new LocalDateTimeDeserializer(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
    }


    // 配置
    @Bean
    public Jackson2ObjectMapperBuilderCustomizer jackson2ObjectMapperBuilderCustomizer() {
        return builder -> {
            builder.serializerByType(LocalDateTime.class, localDateTimeSerializer());
            builder.deserializerByType(LocalDateTime.class, localDateTimeDeserializer());
        };
    }

}