Swagger使用

一、Swagger简介

• 号称世界上最流行的Api框架
• RestFul Api文档在线自动生成工具 => Api文档与Api定义同步更新
• 直接运行，可以在线测试接口
• 支持多种语言（java，php…）

官网：https://swagger.io/

在项目中使用Swagger需要Springfox

• swagger2
• ui

---

二、SpringBoot集成Swagger

1、导入相关依赖
这里不要使用太高版本，可能会出现异常。

		<!-- swagger2 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<!-- swaggerui -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>

出现这种异常
解决办法：
在启动类上加@EnableWebMvc
或者在配置文件中加
spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

打开swagger-ui.html页面出现404异常
解决办法：

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {


    /**
     * 注册资源映射
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        /**
         * 配置swagger-ui显示文档
         */
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

//    /**
//     * 注册资源映射(使用Knfie4j的界面)
//     * @param registry
//     */
//    @Override
//    public void addResourceHandlers(ResourceHandlerRegistry registry) {
//        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
//        /** 配置knife4j 显示文档 */
//        registry.addResourceHandler("doc.html")
//                .addResourceLocations("classpath:/META-INF/resources/");
//        /**
//         * 配置swagger-ui显示文档
//         */
//        registry.addResourceHandler("swagger-ui.html")
//                .addResourceLocations("classpath:/META-INF/resources/");
//        /** 公共部分内容 */
//        registry.addResourceHandler("/webjars/**")
//                .addResourceLocations("classpath:/META-INF/resources/webjars/");
//    }

}

一开始导入的swagger依赖都是3.0.0版本，加了这个config还是报404异常，这里最好用2.9.2版本

---

三、配置Swagger

Swagger的bean实例Docket

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(Environment environment){

        //设置要显示的swagger环境
        //Profiles profile = Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断是否处在自己设定的环境中
        //boolean flag = environment.acceptsProfiles(profile);


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否启用swagger，若为false，则不能在浏览器中访问
                //flag对应上面的需要显示swagger的环境配置
                //.enable(flag)
                .select()
                //RequestHandlerSelectors:配置要扫描借口的方式
                //basePackage:指定要扫描的包
                //any():扫描全部
                //none():不扫描
                //withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation:扫描方法上的注解
           		.apis(RequestHandlerSelectors.basePackage("com.zhangsan.SwaggerStudy.controller"))
                //paths():过滤什么路径
                //.paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo(){
        Contact contact = new Contact("zs","https://baidu.com","123@qq.com");
        return new ApiInfo("MyApiDocumentation",
                "zs",
                "1.0",
                "https://baidu.com",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

若要配置多个分组；多个Docket实例即可

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("A");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("B");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("C");
    }

实体类：

@ApiModel("用户实体类")
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
    @ApiModelProperty("用户名")
    private String userName;
    @ApiModelProperty("密码")
    private String password;
}

Controller:

@Api(tags = "hello控制类")
@RestController
@Slf4j
@RequestMapping("/hello")
public class HelloController {

    @GetMapping()
    public String first(){
        return "hello";
    }

    @ApiOperation("获取用户")
    @GetMapping("/user")
    public User getUser(@RequestParam @ApiParam("用户名") String userName){

        return new User(userName,"123");
    }
}

当controller中返回实体类，被注解的实体类就会出现在swagger中

测试接口：