springboot整合swagger

swagger ui是个挺不错的东西，比起传统的API文档提升的工作效率是显而易见的。我就不多罗嗦了，这里记录一下我的整合过程。

第一步：pom文件中添加对swagger的引用

<!--引入swagger ui-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.8.0</version>
		</dependency>

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

这里版本问题稍微提一下，我试过很多版本，但不是所有的都能用，这可能和所使用的ide是有冲突，添加引用后出现错误不要着急，试着换其它版本试试，我这里也贴一下maven中swagger各版本的链接：

https://mvnrepository.com/artifact/io.springfox/springfox-swagger2

第二步：创建一个swagger的配置类：SwaggerUI

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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;

/**
 * @program: ***
 * @description: 这是一个swagger ui接口调试功能的配置文件
 * @author: huangyy
 * @create: 2018-12-21 16:15
 */
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerUI implements WebMvcConfigurer {
    /**
     * 允许访问swagger的静态资源
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("演示 API")
                .description("描述信息")
                .termsOfServiceUrl("http://www.baidu.com")
                .version("1.0")
                .build();
    }
}

这里有一点需要注意，网上许多资源都是没有继承 WebMvcConfigurer 这个类的，这样做可能有问题也可能没问题，主要看你的springboot项目的架构，我这里不继承这个类是不行的，swagger出不来，原因是访问不了swagger的静态资源文件。在springmvc中整合swagger是需要将swagger的静态资源文件手动拷贝到指定目录下的，这里不需要的。

这里修改一下你controller的包路径就行了。

 

第三步：按需求暴露controller中的接口

@Api(description = "首页测试接口")
@RestController
@RequestMapping("/index")
public class IndexController {

    @Autowired
    private SysWebPageService sysWebPageService;


    @ApiOperation(value = "首页信息",notes = "这是日志")
    @ApiImplicitParam(name = "_id",value = "sys_web_page表中的_id",dataType = "varchar",paramType = "path",required = true)
    @RequestMapping(value = "/hello/{_id}",method = RequestMethod.GET)
    @ResponseBody
    public JsonResult hello(@PathVariable(value = "_id") String _id){
        System.out.println(_id);
        return JsonResult.ok(sysWebPageService.querySysWebPageByIdCustom(_id));
    }



}

到这里基本就完成了；

浏览器查看：http://localhost:8080/swagger-ui.html

 

顺带提一句，这个版本的swagger好丑~~~~

 

补充：

按照以上的写法，swagger是能正常显示的，但是有个很尴尬的问题，在开发中我们会遇到很多要求传入一个实体类的情况，当然这个实体类实际上也是也json的形式，只不过是我们在后台的接口当中以将具体的类把String给替换掉。我们先来看截图：

 

这是swagger 2.4版本的效果，比2.8不知道好看多少倍。经过测试，我发现swagger对浏览器很挑剔，各版本对不同浏览器都有不同的效果，有些干脆就连界面都不给你显示出来。

说重点，在上面这张截图中，我们发现data type不是String的数据类型，而是我们业务需要的一个实体类的内部结构，这样在前段app做开发的时候就更直观了。点击黄色区域，会将数据填充到value中，我们将数据稍加修改，点击try it out便可以测试了，很方便。

下面上controller类中的代码片段：