SpringBoot+Swagger2 四步整合
第一步: 添加相关依赖
- <parent>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter-parent</artifactId>
- <version>1.5.9.RELEASE</version>
- </parent>
- <properties>
- <swagger2.version>2.7.0</swagger2.version>
- </properties>
- <dependencies>
- <!--springBoot 相关依赖 -->
- <dependency>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter-web</artifactId>
- </dependency>
- <!--swagger2 相关依赖 -->
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger2</artifactId>
- <version>${swagger2.version}</version>
- </dependency>
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger-ui</artifactId>
- <version>${swagger2.version}</version>
- </dependency>
- </dependencies>
创建 SrpingBoot 启动类
- /**
- * Springboot+Swagger 整合启动类
- *
- * @author Y.yang
- * @date 2019/3/12
- */
- @SpringBootApplication
- public class SwaggerApplication {
- public static void main(String[] args) {
- SpringApplication.run(SwaggerApplication.class, args);
- }
- }
第二步: 配置 Swagger2
注意添加 @Configuration EnableSwagger2 注解
- /**
- * Swagger2 接口 API 文档 配置文件
- *
- * @author Y.yang
- * @date 2019/3/12
- */
- @Configuration
- @EnableSwagger2
- public class SwaggerConfig {
- /**
- * 初始化创建 Swagger API
- */
- @Bean
- public Docket createRestApi() {
- return new Docket(DocumentationType.SWAGGER_2)
- // 详细信息定制
- .apiInfo(apiInfo())
- .select()
- // 指定当前包路径
- .apis(RequestHandlerSelectors.basePackage("com.fame.controller"))
- // 扫描所有 .apis(RequestHandlerSelectors.any())
- .paths(PathSelectors.any())
- .build();
- }
- /**
- * 添加摘要信息
- */
- private ApiInfo apiInfo() {
- // 用 ApiInfoBuilder 进行定制
- return new ApiInfoBuilder()
- .title("标题: springBoot-Swagger2 整合学习")
- .description("描述: 文档构建器")
- .contact(new Contact("Fame-springBoot-Swagger2", null, null))
- .version("版本号: 1.0")
- .build();
- }
- }
springfox 为我们提供了一个 Docket(摘要的意思)类, 我们需要把它做成一个 Bean 注入到 spring 中,
显然, 我们需要一个配置文件, 并通过一种方式 (显然它会是一个注解) 告诉程序, 这是一个 Swagger 配置文件.
springfox 允许我们将信息组合成一个 ApiInfo 的类, 作为构造参数传给 Docket(当然也可以不构造这个类, 而直接使用 null, 但是你的这个 API 就太 low 了).
第三步: 创建测试实例
- /**
- * Swagger 接口测试
- *
- * @author Y.yang
- * @date 2019/3/12
- */
- @RestController
- public class UserController {
- @GetMapping("/get")
- public String get(){
- return "Hello Swagger2";
- }
- }
第四步: 输入 SwaggerUI 地址
http://localhost:8080/swagger-ui.html
Swagger2 基本使用 - 常用注解
接口 / 方法常用注解
- /**
- * Swagger 接口测试
- *
- * @author Y.yang
- * @date 2019/3/12
- */
- @API(value = "用户信息", tags = { "用户信息" })
- @RestController
- public class UserController {
- @ApiOperation(value = "用户信息分页查询")
- @GetMapping("/page")
- public String page(User user) {
- return "Hello Swagger2";
- }
- @ApiOperation(value = "用户信息查询")
- @ApiImplicitParams({
- @ApiImplicitParam(name = "id", value = "用户 ID", required = true, dataType = "Integer"),
- @ApiImplicitParam(name = "file", value = "文件导入", required = true, dataType = "MultipartFile")
- })
- @GetMapping("/id")
- public UserVo getUser(Long id, MultipartFile file) {
- return new UserVo();
- }
- }
@API: 描述类 / 接口的主要用途
用于类; 表示标识这个类是 swagger 的资源
tags - 表示说明
value - 也是说明, 不会显示在接口文档上, 可以使用 tags 替代
但是 tags 如果有多个值, 会生成多个 list
@API(value = "用户信息", tags = { "用户信息" })
@ApiOperation: 描述方法用途
@ApiOperation(value = "用户信息分页查询")
@ApiImplicitParam: 描述方法的参数
@ApiImplicitParams: 描述方法的参数(Multi-Params)
- @ApiImplicitParams({
- @ApiImplicitParam(name = "id", value = "用户 ID", required = true, dataType = "Integer"),
- @ApiImplicitParam(name = "file", value = "文件导入", dataType = "MultipartFile")
- })
实体类常用注解
- /**
- * 用户信息 数据传输对象 Dto(Data Transfer Object)
- *
- * @author Y.yang
- * @date 2019/3/29
- */
- @ApiModel(description = "用户信息请求对象")
- @Data
- public class User implements Serializable {
- private static final long serialVersionUID = -6986638131456347054L;
- @ApiModelProperty(value = "姓名")
- private String username;
- @ApiModelProperty(value = "性别")
- private String sex;
- @ApiModelProperty(value = "年龄")
- private Integer age;
- }
@ApiModel: 描述实体类(Dto,Vo,Do 等)
@ApiModel(description = "用户信息请求对象")
@ApiModelProperty: 描述实体类的字段
@ApiModelProperty(value = "姓名")
来源: http://www.bubuko.com/infodetail-3009431.html