寫在前面
由於公司項目采用前后端分離，維護接口文檔基本上是必不可少的工作。一個理想的狀態是設計好后，接口文檔發給前端和后端，大伙按照既定的規則各自開發，開發好了對接上了就可以上線了。當然這是一種非常理想的狀態，而手寫文檔雖然可以解決一些問題，但是也存在以下痛點。
還好，有一些工具可以減輕我們的工作量，Swagger2 就是其中之一。
本文以Demo示例展示一下在Spring Boot 中如何整合 Swagger2 。
Swagger2常用注解說明
@Api： 修飾整個類，描述Controller的作用
@ApiOperation： 描述一個類的一個方法，或者說一個接口
@ApiParam： 單個參數描述
@ApiModel： 用對象來接收參數
@ApiModelProperty： 用對象接收參數時，描述對象的一個字段
@ApiResponse： HTTP響應其中1個描述
@ApiResponses： HTTP響應整體描述
@ApiIgnore： 使用該注解忽略這個API
@ApiError ： 發生錯誤返回的信息
@ApiImplicitParam： 一個請求參數
@ApiImplicitParams： 多個請求參數
具體說明如下：
@Api：用在請求的類上，表示對類的說明
tags="說明該類的作用，可以在UI界面上看到的注解"
value="該參數沒什么意義，在UI界面上也看到，所以不需要配置"
@ApiOperation：用在請求的方法上，說明方法的用途、作用
value="說明方法的用途、作用"
notes="方法的備注說明"
@ApiImplicitParams：用在請求的方法上，表示一組參數說明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數的各個方面
name：參數名
value：參數的漢字說明、解釋
required：參數是否必須傳
paramType：參數放在哪個地方
· header --> 請求參數的獲取：@RequestHeader
· query --> 請求參數的獲取：@RequestParam
· path（用於restful接口）--> 請求參數的獲取：@PathVariable
· body（不常用）
· form（不常用）
dataType：參數類型，默認String，其它值dataType="Integer"
defaultValue：參數的默認值
@ApiResponses：用在請求的方法上，表示一組響應
@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
code：數字，例如400
message：信息，例如"請求參數沒填好"
response：拋出異常的類
@ApiModel：用於響應類上，表示一個返回響應數據的信息
（這種一般用在post創建的時候，使用@RequestBody這樣的場景，
請求參數無法使用@ApiImplicitParam注解進行描述的時候）
@ApiModelProperty：用在屬性上，描述響應類的屬性
SpringBoot整合Swagger2進行CRUD操作
數據准備：
數據庫名：springboottest，表名：ss_company
建表語句：
DROP TABLE IF EXISTS ss_company; CREATE TABLE ss_company ( id varchar(40) NOT NULL COMMENT 'ID', name varchar(255) DEFAULT NULL COMMENT '公司名稱', expiration_date datetime DEFAULT NULL COMMENT '到期時間', address varchar(255) DEFAULT NULL COMMENT '公司地址', license_id varchar(255) DEFAULT NULL COMMENT '營業執照-圖片', representative varchar(255) DEFAULT NULL COMMENT '法人代表', phone varchar(255) DEFAULT NULL COMMENT '公司電話', company_size varchar(255) DEFAULT NULL COMMENT '公司規模', industry varchar(255) DEFAULT NULL COMMENT '所屬行業', remarks varchar(255) DEFAULT NULL COMMENT '備注', state int(2) DEFAULT '1' COMMENT '狀態', balance double DEFAULT NULL COMMENT '當前余額', city varchar(20) DEFAULT NULL, PRIMARY KEY (id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
數據插入語句：
INSERT INTO ss_company VALUES ('1', '字節跳動', null, '北京', 'xxx002', '張某', '123', '10000人以上', '互聯網', '互聯網公司', '1', '100', '北京'); INSERT INTO ss_company VALUES ('2', '百度', null, '北京市海淀區', 'bzd001', '李某', '110', '5000-10000人', '計算機', '', '1', '100', '北京'); INSERT INTO ss_company VALUES ('3', '阿里巴巴', null, '中國杭州市濱江區', 'bzd002', '馬某', '110', '5000-10000人', '電子商務', '', '1', '100', '杭州'); INSERT INTO ss_company VALUES ('4', '騰訊', null, '深圳市南山區', 'bzd003', '馬某', '110', '5000-10000人', '游戲', '', '1', '100', '深圳');
1> 創建SpringBoot工程，導入pom文件依賴
application.yml配置：
spring:
datasource:
driver-class-name: com.mysql.jdbc.Driver
url: jdbc:mysql://localhost:3306/springboottest?characterEncoding=utf-8
username: root
password: root
server:
port: 8090
pom依賴：
<dependencies> <!-- SpringBoot 啟動器 web依賴 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- swagger2文檔配置依賴 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <!--jdbc--> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-jdbc</artifactId> </dependency> <!--springboot支持的是jpa,mybatisplus自己做了啟動器--> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>3.2.0</version> </dependency> <!--mysql--> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>5.1.47</version> </dependency> <!-- lombok插件依賴 --> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> <!-- SpringBoot測試啟動依賴 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> <exclusions> <exclusion> <groupId>org.junit.vintage</groupId> <artifactId>junit-vintage-engine</artifactId> </exclusion> </exclusions> </dependency> </dependencies>
2> 創建pojo實體類
import com.baomidou.mybatisplus.annotation.IdType; import com.baomidou.mybatisplus.annotation.TableId; import com.baomidou.mybatisplus.annotation.TableName; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; import java.io.Serializable; import java.util.Date; @Data @TableName("ss_company") @ApiModel(value = "公司實體類") public class Company implements Serializable { /** * AUTO : AUTO(0, "數據庫ID自增"), * INPUT : INPUT(1, “用戶輸入ID”), * ID_WORKER : ID_WORKER(2, "全局唯一ID"),默認值如果不設置會在用該策略 * UUID : UUID(3, "全局唯一ID"), * NONE : NONE(4, "該類型為未設置主鍵類型"), * ID_WORKER_STR : ID_WORKER_STR(5, "字符串全局唯一ID"); */ @TableId(type = IdType.UUID) @ApiModelProperty(value = "主鍵Id") private String id; @ApiModelProperty(value = "公司名稱") private String name; @ApiModelProperty(value = "到期時間") private Date expirationDate; @ApiModelProperty(value = "公司地址") private String address; @ApiModelProperty(value = "營業執照") private String licenseId; @ApiModelProperty(value = "法人代表") private String representative; @ApiModelProperty(value = "公司電話") private String phone; @ApiModelProperty(value = "公司規模") private String companySize; @ApiModelProperty(value = "所屬行業") private String industry; @ApiModelProperty(value = "備注") private String remarks; @ApiModelProperty(value = "公司狀態") private Integer state; @ApiModelProperty(value = "當前余額") private Double balance; @ApiModelProperty(value = "公司所在地") private String city; private static final long serialVersionUID = 1L; }
3> 創建Result類(建議)
備注：Result類主要是在測試的時候，給出提示信息
import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import java.io.Serializable; @ApiModel(value = "返回結果類") public class Result implements Serializable { @ApiModelProperty(value = "狀態判斷") private boolean success; @ApiModelProperty(value = "返回消息內容") private String message; public Result(boolean success,String message) { this.message = message; this.success = success; } public boolean isSuccess() { return success; } public void setSuccess(boolean success) { this.success = success; } public String getMessage() { return message; } public void setMessage(String message) { this.message = message; } }
4> 創建Dao接口
備注：由於com.baomidou.mybatisplus.core.mapper包已經封裝了CRUD功能，所以這里的Dao接口只需繼承對應的BaseMapper<Company>接口就可以了
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
public interface CompanyDao extends BaseMapper<Company> { }
5> 創建Service接口
import java.util.List; public interface CompanyService { //查詢所有 List<Company> findAll(); //單一查詢 Company findOne(String id); //更新 void update(Company company); //添加 void add(Company company); //刪除 void delete(String id); }
6> 創建ServiceImpl實現類
import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Service; import java.util.List; @Service public class CompanyServiceImpl implements CompanyService { @Autowired private CompanyDao companyDao; @Override public List<Company> findAll() { return companyDao.selectList(null); } @Override public Company findOne(String id) { return companyDao.selectById(id); } @Override public void update(Company company) { companyDao.updateById(company); } @Override public void add(Company company) { companyDao.insert(company); } @Override public void delete(String id) { companyDao.deleteById(id); } }
7> 創建Controller類
import io.swagger.annotations.*; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; import java.util.List; @Api("Swagger示例CRUD操作") @RestController @RequestMapping("/company") public class CompanyController { @Autowired private CompanyService companyService; //查詢所有 @ApiOperation("獲取公司列表") @GetMapping public List<Company> findAll(){ return companyService.findAll(); } //查詢單一 @ApiOperation(value = "根據id獲取公司信息",notes = "id必須是數字") @ApiImplicitParams({@ApiImplicitParam(name = "id",value = "id",required = true,paramType = "path")}) @ApiResponses({@ApiResponse(code=400,message="id為空")}) @GetMapping("/{id}") public Company findById(@PathVariable("id") String id){ return companyService.findOne(id); } //添加 @ApiOperation("新增公司信息") @ApiImplicitParam(name = "company", value = "單個公司信息", dataType = "Company") @PostMapping public Result add(@RequestBody Company company){ try { companyService.add(company); return new Result(true,"新增成功"); } catch (Exception e) { e.printStackTrace(); return new Result(false,"新增失敗"); } } //修改 @ApiOperation("修改公司信息") @ApiImplicitParam(name = "company", value = "單個公司信息", dataType = "Company") @PutMapping public Result update(@RequestBody Company company){ try { companyService.update(company); return new Result(true,"修改成功"); } catch (Exception e) { e.printStackTrace(); return new Result(false,"修改失敗"); } } //刪除 @ApiOperation("刪除用戶") @ApiImplicitParam(name = "id", value = "單個用戶信息", dataType = "String") @DeleteMapping("/{id}") public Result delete(@PathVariable("id") String id){ try { companyService.delete(id); return new Result(true,"刪除成功"); } catch (Exception e) { e.printStackTrace(); return new Result(false,"刪除失敗"); } } }
8> 創建Controller類
import io.swagger.annotations.*; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; import java.util.List; @Api(tags = "Swagger示例CRUD操作") @RestController @RequestMapping("/company") public class CompanyController { @Autowired private CompanyService companyService; //查詢所有 @ApiOperation("獲取公司列表") @GetMapping public List<Company> findAll(){ return companyService.findAll(); } //查詢單一 @ApiOperation(value = "根據id獲取公司信息",notes = "id必須是數字") @ApiImplicitParams({@ApiImplicitParam(name = "id",value = "id",required = true,paramType = "path")}) @ApiResponses({@ApiResponse(code=400,message="id為空")}) @GetMapping("/{id}") public Company findById(@PathVariable("id") String id){ return companyService.findOne(id); } //添加 @ApiOperation("新增公司信息") @ApiImplicitParam(name = "company", value = "單個公司信息", dataType = "Company") @PostMapping public Result add(@RequestBody Company company){ try { companyService.add(company); return new Result(true,"新增成功"); } catch (Exception e) { e.printStackTrace(); return new Result(false,"新增失敗"); } } //修改 @ApiOperation("修改公司信息") @ApiImplicitParam(name = "company", value = "單個公司信息", dataType = "Company") @PutMapping public Result update(@RequestBody Company company){ try { companyService.update(company); return new Result(true,"修改成功"); } catch (Exception e) { e.printStackTrace(); return new Result(false,"修改失敗"); } } //刪除 @ApiOperation("刪除用戶") @ApiImplicitParam(name = "id", value = "單個用戶信息", dataType = "String") @DeleteMapping("/{id}") public Result delete(@PathVariable("id") String id){ try { companyService.delete(id); return new Result(true,"刪除成功"); } catch (Exception e) { e.printStackTrace(); return new Result(false,"刪除失敗"); } } }
9> 創建Swagger2配置類
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; @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(restApiInfo()) .select() // 指定包名 .apis(RequestHandlerSelectors.basePackage("com.darren.springbootswaggerdemo.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo restApiInfo() { return new ApiInfoBuilder() .title("springboot利用swagger2構建api文檔") .description("簡單優雅的restful風格") .termsOfServiceUrl("no terms of serviceUrl") .version("1.0") .build(); } }
備注說明：
這里提供的配置類，首先通過 @EnableSwagger2 注解啟用 Swagger2 ，然后配置一個 Docket Bean，這個 Bean 中，配置映射路徑和要掃描的接口的位置，
在 apiInfo 中，主要配置一下 Swagger2 文檔網站的信息，例如網站的 title，網站的描述，聯系人信息，使用的協議，版本信息，許可證信息等等。
至此，SpringBoot整合Swagger2示例Demo已配置完成，下面啟動SpringBoot啟動類測試，然后打開瀏覽器，在地址欄中輸入：
http://localhost:8090/swagger-ui.html
能夠看到如下界面，說明配置已成功
可以看到，所有的接口這里都列出來了，包括接口請求方式，接口地址以及接口的名字等，點開一個接口，可以看到如下信息，
點擊右上角的 Try it out，就可以進行接口測試：
點擊 Execute 按鈕，表示發送請求進行測試。測試結果會展示在下面的 Response 中。
除此之外，其他的功能測試，還有一些響應值的注解，大家也都可以自己摸索下。
至此，SpringBoot整合Swagger2示例已完成，又可以浪一會啦。。。。。。。。。。。。。。。。