Swagger

1.swagger介紹

現在開發，很多采用前後端分離的模式，前端隻負責調用接口，進行渲染，前端和後端的唯一聯系，變成了API接口。是以，API文檔變得越來越重要。swagger是一個友善我們更好的編寫API文檔的架構，而且swagger可以模拟http請求調用。

大部分采取的方式：Vue + SpringBoot，Vue通過js渲染頁面，後端把資料傳遞給js，早期前端隻負責寫頁面，然後把寫好的HTML頁面給後端，後端使用模闆引擎（Jsp，Thymeleaf、 freemarker）進行開發。

前後端分離的好處：各自開發，相對獨立，松耦合，前後端通過API進行互動，後端提供接口給前端，前端去調用該接口，但可能會導緻前後端團隊人員不能做到及時協商，出現一些問題。解決方式：早期使用實時更新文檔，但非常繁瑣，後來又使用postman來進行一些測試。

swagger是目前最流行的Api架構，官網：

https://swagger.io/

2.springboot中內建swagger使用步驟：

導入依賴

io.springfox

springfox-swagger-ui

2.9.2

springfox-swagger2

建立配置類

@Configuration

@EnableSwagger2//開啟Swagger2

public class SwaggerConfig {

}

然後啟動測試運作，通路：

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

，看到如下頁面：

手動配置執行個體，修改SwaggerConfig配置類

package com.qf.swagger.config;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

//配置Swagger的Bean執行個體

@Bean

public Docket swaggerSpringMvcPlugin() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo());

//配置API的基本資訊（會在

http://

項目實際位址/swagger-ui.html頁面顯示）

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("測試API文檔标題")

.description("測試api接口文檔描述")

.termsOfServiceUrl("http://www.baidu.com")

.version("1.0")

.build();

然後再次重新開機測試運作：

建立實體類

package com.qf.swagger.entity;

import io.swagger.annotations.ApiModel;

import io.swagger.annotations.ApiModelProperty;

@ApiModel("使用者實體類")

public class User {

@ApiModelProperty("使用者名")

private String username;

@ApiModelProperty("密碼")

private String password;

public String getUsername() {

return username;

public void setUsername(String username) {

this.username = username;

public String getPassword() {

return password;

public void setPassword(String password) {

this.password = password;

建立controller

package com.qf.swagger.controller;

import com.qf.swagger.entity.User;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiOperation;

import io.swagger.annotations.ApiParam;

import org.springframework.web.bind.annotation.GetMapping;

import org.springframework.web.bind.annotation.PostMapping;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RestController;

@Api(description ="使用者管理API")

@RestController

public class UserController {

@ApiOperation("添加使用者")

@PostMapping("/add")

public User add(@ApiParam("使用者名") String username,@ApiParam("密碼") String password){

return new User();

@ApiOperation("修改使用者")

@PostMapping("/update")

public String update(){

return "修改";

@ApiOperation("删除使用者")

@GetMapping("/delete")

public Boolean delete(@ApiParam("使用者編号") Integer id){

return true;

@ApiOperation("查詢使用者")

@RequestMapping("/query")

public User query(){

User user = new User();

user.setUsername("jack");

user.setPassword("1234");

return user;

修改SwaggerConfig配置類

.apiInfo(apiInfo())

.groupName("yangl")//分組名稱(可以建立多個Docket就有多個組名)

.enable(true)//enable表示是否開啟Swagger

.select()

//RequestHandlerSelectors指定掃描的包

.apis(RequestHandlerSelectors.basePackage("com.qf.swagger.controller"))

swagger通過注解表明該接口會生成文檔，包括接口名、請求方法、參數、傳回資訊

@Api：修飾整個類，描述Controller的作用

@ApiOperation：描述一個類的一個方法，或者說一個接口

@ApiModel：用對象來接收參數 ，修飾類

@ApiModelProperty：用對象接收參數時，描述對象的一個字段

@ApiResponse：HTTP響應其中1個描述

@ApiResponses：HTTP響應整體描述，一般描述錯誤的響應

@ApiIgnore：使用該注解忽略這個API

@ApiError ：發生錯誤傳回的資訊

@ApiParam：單個參數描述

@ApiImplicitParam：一個請求參數，用在方法上

@ApiImplicitParams：多個請求參數