Springboot整合Swagger2

一、什么是Swagger2？
Swagger是一个RESTFUL 接口的文档在线自动生成和功能测试的框架。
Swagger 是一个规范和完整的框架。用于生成、描述、调用和可视化RestFul风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法、参数和模型紧密集成到服务器的代码，允许Api 来始终保持同步，Swagger让部署管理和使用功能强大的Api。

手写Api文档的几个痛点：
文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
接口返回结果不明确
不能直接在线测试接口，通常需要使用工具，比如postman
接口文档太多，不好管理

Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

二、引入jar包依赖

<!-- Swagger2 -->
        <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>

三、添加Swagger配置类

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;

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.test"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Quotation System API")          
                .contact("Jackson ")
                .version("1.0")
                .build();
    }
}

四、编写接口测试
LoginController.java

@RestController
@Slf4j
public class LoginController {

    @ApiOperation(value="登录界面", notes="")
    @RequestMapping(value = "/login.html",method = RequestMethod.GET)
    public ModelAndView test() {
        ModelAndView modelAndView = new ModelAndView();
        modelAndView.addObject("username", "jackson");
        modelAndView.setViewName("hui/login");
        return modelAndView;
    }

    @ApiOperation(value="404 not found页面", notes="")
    @RequestMapping(value = "/404.html",method = RequestMethod.GET)
    public ModelAndView page404() {
        return new ModelAndView("/hui/404");
    }

    @ApiOperation(value="没有权限页面", notes="")
    @RequestMapping(value = "/unauthorized.html",method = RequestMethod.GET)
    public ModelAndView unauthorized(){
        return new ModelAndView("/hui/_blank");
    }
}

Swagger常用注解
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

五、访问测试
启动springboot项目，访问http://localhost:端口号/项目Context-path/swagger-ui.html
如：http://localhost:8088/quotation/swagger-ui.html

六、若出现访问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 MyWebAppConfigurer implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        // 解决 SWAGGER2 404报错
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

    }
}