一、介紹Swagger2
Swagger是一款RESTful接口的文檔在線自動生成、功能測試功能框架。一個規範和完整的框架,用於生成、描述、調用和可視化RESTful風格的Web服務,加上swagger-ui,可以有很好的呈現。
二、常用註解
這裏是說明常用註解的含義和基本用法(也就是說已經對swagger進行集成完成)
沒有集成的請參見
SpringBoot集成springfox-swagger2構建restful API
SpringMVC集成springfox-swagger2構建restful API
官網WIKI
常用註解:
註解 | 作用處 | 描述 |
---|---|---|
@Api | 用於類 | 表示標識這個類是swagger的資源 |
@ApiOperation | 用於方法 | 表示一個http請求的操作 |
@ApiParam | 用於方法,參數,字段說明 | 表示對參數的添加元數據(說明或是否必填等) |
@ApiModel | 用於類 | 表示對類進行說明,用於參數用實體類接收 |
@ApiModelProperty | 用於方法,字段 | 表示對model屬性的說明或者數據操作更改 |
@ApiIgnore | 用於類,方法,方法參數 | 表示這個方法或者類被忽略 |
@ApiImplicitParam | 用於方法 | 表示單獨的請求參數 |
@ApiImplicitParams | 用於方法 | 包含多個 @ApiImplicitParam |
1、@Api()
用於類;表示標識這個類是swagger的資源
- tags–表示說明
- value–也是說明,可以使用tags替代
但是tags如果有多個值,會生成多個list
@Api(value="用戶controller",tags={"用戶操作接口"})
@RestController
public class UserController {
}
效果:
2、@ApiOperation()
用於方法;表示一個http請求的操作
- value用於方法描述
- notes用於提示內容
- tags可以重新分組(視情況而用)
3、@ApiParam()
用於方法,參數,字段說明;表示對參數的添加元數據(說明或是否必填等)
- name–參數名
- value–參數說明
- required–是否必填
@Api(value="用戶controller",tags={"用戶操作接口"})
@RestController
public class UserController {
@ApiOperation(value="獲取用戶信息",tags={"獲取用戶信息copy"},notes="注意問題點")
@GetMapping("/getUserInfo")
public User getUserInfo(@ApiParam(name="id",value="用戶id",required=true) Long id,@ApiParam(name="username",value="用戶名") String username) {
// userService可忽略,是業務邏輯
User user = userService.getUserInfo();
return user;
}
}
效果圖:
4、@ApiModel()
用於類 ;表示對類進行說明,用於參數用實體類接收
- value–表示對象名
- description–描述
都可省略
5、@ApiModelProperty()
用於方法,字段; 表示對model屬性的說明或者數據操作更改
- value–字段說明
- name–重寫屬性名字
- dataType–重寫屬性類型
- required–是否必填
- example–舉例說明
- hidden–隱藏
entity bean類
@ApiModel(value="user對象",description="用戶對象user") public class User implements Serializable{ private static final long serialVersionUID = 1L; @ApiModelProperty(value="用戶名",name="username",example="xingguo") private String username; @ApiModelProperty(value="狀態",name="state",required=true) private Integer state; private String password; private String nickName; private Integer isDeleted; @ApiModelProperty(value="id數組",hidden=true) private String[] ids; private List<String> idList; //省略get/set }
@ApiOperation("更改用戶信息") @PostMapping("/updateUserInfo") public int updateUserInfo(@RequestBody @ApiParam(name="用戶對象",value="傳入json格式",required=true) User user){ int num = userService.updateUserInfo(user); return num; }
效果圖:
6、@ApiIgnore()
用於類或者方法上,可以不被swagger顯示在頁面上
比較簡單, 這裏不做舉例
7、@ApiImplicitParam()
用於方法
表示單獨的請求參數
8、@ApiImplicitParams()
用於方法,包含多個 @ApiImplicitParam
- name–參數ming
- value–參數說明
- dataType–數據類型
- paramType–參數類型
- example–舉例說明
@ApiOperation("查詢測試")
@GetMapping("select")
//@ApiImplicitParam(name="name",value="用戶名",dataType="String", paramType = "query")
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用戶名",dataType="string", paramType = "query",example="xingguo"),
@ApiImplicitParam(name="id",value="用戶id",dataType="long", paramType = "query")})
public void select(){
}
效果圖:
三、springboot集成
1、添加maven依賴
<!--swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.marvin.demo</groupId>
<artifactId>SpringBoot_Swagger_learn_demo</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>
<name>SpringBoot_Swagger_learn_demo</name>
<!--引用springBoot-->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.4.RELEASE</version>
</parent>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--引入lombok-->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.16.18</version>
</dependency>
<!--引入swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
</dependencies>
<build>
<plugins>
<!--配置boot運行插件-->
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
2、配置啓動類
添加註解@EnableSwagger2
package com.marvin.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class);
}
}
3、編寫配置文件(SwaggerConfig.java)
定義Docket的bean類
package com.marvin.demo.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;
@Configuration
public class SwaggerConfig {
/**
* 初始化創建Swagger Api
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)// 詳細信息定製
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com"))//指定包路徑,掃描com路徑下的api文檔
.paths(PathSelectors.any())//路徑判斷
.build();
}
/**
* 添加摘要信息(會在界面顯示的信息)
*/
private ApiInfo apiInfo() {
// 用ApiInfoBuilder進行定製
return new ApiInfoBuilder()
.title("Swagger開發規範")//標題
.description("Saggger開發描述")
.termsOfServiceUrl("http://baidu.com")//(不可見)條款地址
.version("1.0.0")//版本號
.build();
}
}
4、controller 和 entity
5、結果測試
默認地址:http://localhost:8080/swagger-ui.html