Swagger是一款好用的
Java接口文档工具
,引入Maven坐标之后就可以在项目启动之后,通过访问相应的地址可以看到生成好的接口文档。
一、页面效果1
访问地址: http://localhost:8081/swagger-ui.html
二、页面效果2
访问地址: http://localhost:8081/doc.html
依赖:
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- 页面效果1 依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- 页面效果2 依赖 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
三、Swagger配置类
注意:@Profile("dev")
: swagger只在 spring.profiles.active=dev
时生效,对Maven中的<profiles>
不生效。
import io.swagger.annotations.ApiOperation;
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;
import java.util.HashSet;
import java.util.Set;
/**
* <p> @Title SwaggerConfig
* <p> @Description Swagger 配置类
*
* @author ACGkaka
* @date 2021/4/23 15:40
*/
@Profile("dev")
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket buildDocket() {
/// accessToken 请求头要求
// ParameterBuilder ticketPar = new ParameterBuilder();
// List<Parameter> parameters = new ArrayList<>();
// ticketPar.name("accessToken").description("accessToken")
// .modelRef(new ModelRef("string")).parameterType("header")
// .required(false).build();
// parameters.add(ticketPar.build());
Set<String> consumes = new HashSet<>();
consumes.add("multipart/form-data");
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// .apis(RequestHandlerSelectors.any())
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build()
// .globalOperationParameters(parameters)
.consumes(consumes);
}
private ApiInfo apiInfo() {
// 作者信息,姓名、网址、邮箱
Contact contact = new Contact("ACGkaka", "https://acgkaka.github.io/", "123123@163.com");
return new ApiInfoBuilder()
.title("Demo System")
.description("Demo System API")
.contact(contact)
.version("V1.0")
.build();
}
}
四、接口注解形式
注解属性说明:
name:参数变量;
value:参数说明;
dataType:数据类型,取值范围:
int
、String
、string
等;
- 如果是 Integer 等原类型包装类,文档中展示的参数类型会变成ref,如下图所示;
- 如果是 User 这种自定义类,可以通过添加@ApiModel注解进行类型说明;
paramType:传输方式,取值范围:
header
–>放在请求头。请求参数的获取:@RequestHeader(代码中接收注解);query
–>用于get请求的参数拼接。请求参数的获取:@RequestParam(代码中接收注解);path
(用于restful接口)–>请求参数的获取:@PathVariable(代码中接收注解);body
–>放在请求体。请求参数的获取:@RequestBody(代码中接收注解);form
(不常用)。
dataType 各种类型展示测试:
import com.demo.swagger.query.DemoQueryParam;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
/**
* <p> @Title DemoController
* <p> @Description Controller 接口
*
* @author ACGkaka
* @date 2021/4/24 23:35
*/
@Api(tags = "接口类")
@RestController
@RequestMapping("/demo")
public class DemoController {
@ApiOperation("get接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "主键", dataType = "String", paramType = "json", required = true)
})
@GetMapping("/get")
public String get(String id) {
return id;
}
@ApiOperation("post接口")
@PostMapping("/post")
public DemoQueryParam post(@RequestBody DemoQueryParam param) {
return param;
}
}
五、POST 请求体注解
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
* <p> @Title DemoQueryParam
* <p> @Description Demo 请求体
*
* @author ACGkaka
* @date 2021/4/24 23:41
*/
@Data
@ApiModel(description = "请求入参")
public class DemoQueryParam {
/**
* 主键
*/
@ApiModelProperty(value = "主键", required = true)
private String id;
/**
* 姓名
*/
@ApiModelProperty(value = "姓名", required = true)
private String name;
/**
* 年龄
*/
@ApiModelProperty("年龄")
private Integer age;
}
整理完毕,完结撒花~