Swagger基础

1.Swagger+Springboot使用步骤

（1）配置pom.xml文件

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>

（2）增加启动类注解@EnableSwagger2

@SpringBootApplication
@EnableSwagger2
public class DemoApplication {
   public static void main(String[] args) {
      SpringApplication.run(DemoApplication.class, args);
   }
}

（3）创建Swagger配置类（最好和启动类在同级目录）

@Configuration
@EnableSwagger2
public class Swagger2 extends WebMvcConfigurationSupport {

    @Bean
    public Docket createApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Swagger2")
                .description("RESTful API接口")
                .version("1.0.0")
                .build();
    }

    /**
     * 解决swagger-ui.html 404无法访问的问题
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("*")
                .allowedMethods("GET", "POST", "PUT", "OPTIONS", "DELETE", "PATCH")
                .allowCredentials(true).maxAge(3600);
    }

}

（4）Controller类添加注解

类添加@Api

方法添加@ApiOperation

@RestController
@Api(value = "用户")
public class UserController {
   
    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());

    @ApiOperation(value="获取用户列表", notes="获取用户列表")
    @RequestMapping(value={""}, method=RequestMethod.GET)
    public List<User> getUserList() {
        List<User> r = new ArrayList<User>(users.values());
        return r;
    }

}

（5）启动springboot程序

访问：http://localhost:8080/api/swagger-ui.html

项目名称：api

项目端口号：8080

2.常用注解

注解	注解含义	备注
@Api	标识这个类是swagger的资源	用于类
@ApiOperation	标识这个方法是swagger的资源	用于方法
@ApiImplicitParam	指定一个请求参数的各个方面	用于方法
@ApiIgnore	指定这个类或者方法不在swagger界面上显示	用于类、方法

@Api(value="XXX",tags={"XXX"})

tags——表示说明
value——也是说明，可以使用tags替代

@ApiOperation(value="XXX",httpMethod="XXX",response= "XXX",notes="XXX"）

value——接口说明

httpMethod——接口请求方式

response——接口返回参数类型

notes——接口发布说明

@ApiImplicitParam(name = "lon", value = "纬度", dataType = "double", paramType = "query", required = true, defaultValue = "111")

name——参数名

value——参数的汉字说明、解释

required——参数是否必须传

paramType——参数放在哪个地方

header——请求参数的获取：@RequestHeader

query——请求参数的获取：@RequestParam

path（用于restful接口）——请求参数的获取：@PathVariable

body（不常用）

form（不常用）

dataType——参数类型，默认String，其它值dataType="Integer"

defaultValue——参数的默认值

@ApiIgnore

3.SpringBoot集成Swagger-Bootstrap-UI

SpringBoot集成Swagger-Bootstrap-UI，页面更清爽！_好好学java-CSDN博客

（1）pom.xml

<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>swagger-bootstrap-ui</artifactId>
			<version>1.8.6</version>
		</dependency>
		<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.9.2</version>
		</dependency>

（2）增加启动类注解@EnableSwagger2

@SpringBootApplication
@EnableSwagger2
public class DemoApplication {
   public static void main(String[] args) {
      SpringApplication.run(DemoApplication.class, args);
   }
}

4.问题汇总

1. swagger-bootstrap-ui里，无法实现文件上传

解决方案：

添加注解

@ApiImplicitParam(value = "上传文件",name = "file",required = true,allowMultiple = true,dataType = "MultipartFile")

2.配置非必要参数

@ApiImplicitParam(name = "pageSize", value = "分页数量", dataType = "Integer", paramType = "query",required = false)

不可以增加默认参数

3.Swagger-Bootstrap-UI里，界面显示参数类型为ref,和配置的不一致

number:Float,Double,float,double

integer:int,Long,long

ref:Integer,short

4.同时接收文件和对象数据

    @RequestMapping(value = "/addFile", method = RequestMethod.POST)
    @ApiImplicitParam(name = "file", value = "文件", required = true, allowMultiple = true, dataType = "MultipartFile")
    public String addFile(MultipartFile file, User usr) {

        return "";
    }