十八、Spring Boot 整合 Swagger3（接口文档）

十八、Spring Boot 整合 Swagger 3（接口文档）

• • （一）Spring Boot项目创建
  • （二）添加依赖
  • （三）修改配置
  • （四）接口描述
  • （五）Swagger 常用注解

（一）Spring Boot项目创建

参考：spring boot 项目创建

（二）添加依赖

pom文件添加 Swagger依赖：

 		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

（三）修改配置

package com.ikaros.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi
@EnableWebMvc
public class SwaggerConfig {
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                // 是否开启swagger
                .enable(true)
                .select()
                // apis： 添加swagger接口提取范围
                .apis(RequestHandlerSelectors.basePackage("com.ikaros.controller"))
                // 指定路径处理，PathSelectors.any()代表不过滤任何路径
                .paths(PathSelectors.any())
                .build();
    }


    @SuppressWarnings("all")
    private ApiInfo apiInfo(){ // 项目相关信息
        return new ApiInfoBuilder()
                .title("Swagger3测试文档")
                .description("文档描述信息")
                .contact(new Contact("deserts", "#", "2569509245@qq.com"))
                .version("1.0")
                .build();
    }
}

（四）接口描述

接口添加描述信息：

@Api(value = "用户", tags = "用户管理")
@Controller
public class UserController {
    @ApiOperation(value = "首页")
    @GetMapping("/")
    public String index() {
        return "index";
    }
}

（五）Swagger 常用注解

Swagger 常用注解：

其它 ：

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
	@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
		name：参数名
		value：参数的汉字说明、解释
		required：参数是否必须传
		paramType：参数放在哪个地方
			· header --> 请求参数的获取：@RequestHeader
			· query --> 请求参数的获取：@RequestParam
			· path（用于restful接口）--> 请求参数的获取：@PathVariable
			· div（不常用）
			· form（不常用）
		dataType：参数类型，默认String，其它值dataType="Integer"
		defaultValue：参数的默认值
	
@ApiResponses：用在请求的方法上，表示一组响应
	@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
		code：数字，例如400
		message：信息，例如"请求参数没填好"
		response：抛出异常的类