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.contentenabled: trueversion: 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* 服務端返回給客戶端內容* */@Beanpublic LocalDateTimeSerializer localDateTimeSerializer() {return new LocalDateTimeSerializer(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));}/** 反序列化內容*   String -> LocalDateTime* 客戶端傳入服務端數據* */@Beanpublic LocalDateTimeDeserializer localDateTimeDeserializer() {return new LocalDateTimeDeserializer(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));}// 配置@Beanpublic Jackson2ObjectMapperBuilderCustomizer jackson2ObjectMapperBuilderCustomizer() {return builder -> {builder.serializerByType(LocalDateTime.class, localDateTimeSerializer());builder.deserializerByType(LocalDateTime.class, localDateTimeDeserializer());};}}