1. 在pom.xml檔案引入Jar包：
<!-- 用于JSON API文檔的生成-->
<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>
2. 配置swagger：
- 在項目建立目錄configuration,在目錄内建立類SwaggerConfig
package springboot.demo.swagger.configuration;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author Administrator on 2019/10/26.
* @version 1.0
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder().title("XXX系統API文檔")
.description("XXX系統API接口文檔描述")
.version("1.0").build())
.select()
.apis(RequestHandlerSelectors.basePackage("項目基礎包名"))
.paths(PathSelectors.any())
.build();
}
}
接下來通路預設http://127.0.0.1:8080/swagger-ui.html位址，就可以通路接口文檔位址了
3.添加swagger注解，生成api文檔
Controller層：
package springboot.demo.swagger.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
import springboot.demo.swagger.entity.User;
/**
* @author Administrator on 2019/10/26.
* @version 1.0
*/
@RestController
@RequestMapping("user")
@Api(tags = "使用者API接口")
public class UserController {
@GetMapping()
@ApiOperation(value = "查詢使用者清單資料")
public String list() {
return "查詢清單資料!";
}
@GetMapping("{id}")
@ApiOperation(value = "查詢單個使用者資料", notes = "提示xxxx")
public String find(@ApiParam(name="id",value="使用者id",required=true) @PathVariable Integer id) {
return String.format("根據主鍵查詢資料: %d", id);
}
@PostMapping()
@ApiOperation(value = "添加新使用者")
public void add(@ApiParam(name="user",value="使用者對象",required=true) User user) {
System.out.println("插入資料!");
}
@PutMapping()
@ApiOperation(value = "修改使用者")
public void update(@ApiParam(name="user",value="使用者對象",required=true) User user) {
System.out.println("修改使用者資料");
}
@DeleteMapping("{id}")
@ApiOperation(value = "删除使用者")
public String delete(@ApiParam(name="id",value="使用者id",required=true) @PathVariable Integer id) {
return String.format("根據主鍵删除記錄: %d", id);
}
}
@Api() 用于類；
表示辨別這個類是swagger的資源
tags–表示說明
value–也是說明，可以使用tags替代
@ApiOperation() 用于方法；表示一個http請求的操作
value用于方法描述
notes用于提示内容
tags可以重新分組（視情況而用）
@ApiParam() 用于方法，參數，字段說明；表示對參數的添加中繼資料（說明或是否必填等）
name–參數名
value–參數說明
required–是否必填
效果圖：
實體類層：
package springboot.demo.swagger.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import javax.validation.constraints.Email;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.Size;
import java.util.Date;
/**
* @author Administrator on 2019/10/26.
* @version 1.0
*/
@Data
@ApiModel(value="user對象",description="user對象描述")
public class User {
/**
* 使用者 ID
*/
@ApiModelProperty(name = "id", value = "主鍵", hidden = true)
private Long id;
/**
* 使用者名
*/
@ApiModelProperty(name = "username", value = "使用者名", dataType = "string",example = "admin")
@Size(min = 4, max = 10, message = "{range}")
private String username;
/**
* 密碼
*/
@ApiModelProperty(name = "password", value = "密碼", dataType = "string",example = "123456")
private String password;
/**
* 郵箱
*/
@ApiModelProperty(name = "email", value = "郵箱", dataType = "string",example = "[email protected]")
@Size(max = 50, message = "{noMoreThan}")
@Email(message = "{email}")
private String email;
/**
* 狀态 0鎖定 1有效
*/
@ApiModelProperty(name = "status", value = "是否有效0=無效，1=有效", dataType="int",example = "1")
@NotBlank(message = "{required}")
private String status;
/**
* 建立時間
*/
@ApiModelProperty(name = "createTime", value = "建立時間", hidden = true)
private Date createTime;
/**
* 修改時間
*/
@ApiModelProperty(name = "modifyTime", value = "修改時間", hidden = true)
private Date modifyTime;
/**
* 性别 0男 1女 2 保密
*/
@ApiModelProperty(name = "sex", value = "0=女，1=男", dataType="int",example = "1")
@NotBlank(message = "{required}")
private String sex;
}
@ApiModel() 用于類 ；表示對類進行說明，用于參數用實體類接收
value–表示對象名
description–描述
都可省略
@ApiModelProperty() 用于方法，字段； 表示對model屬性的說明或者資料操作更改
value–字段說明
name–重寫屬性名字
dataType–重寫屬性類型
required–是否必填
example–舉例說明
hidden–隐藏
