SpringMVC整合SpringFox实践总结

项目中使用的swagger框架在生成api文档时存在一些问题:
1、 控制器下方法无法点击展开
2、api内容结构混乱

基于上述原因，重新整合重构了一下api文档生成的代码。在此将重整过程记录下来，方便后续查看。

Maven依赖引入

要整合SpringFox所需的依赖如下：

        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.6.1version>
        dependency>
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.6.1version>
        dependency>

        
        <dependency>
            <groupId>com.fasterxml.jackson.coregroupId>
            <artifactId>jackson-annotationsartifactId>
            <version>${version.jackson}version>
        dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.coregroupId>
            <artifactId>jackson-databindartifactId>
            <version>${version.jackson}version>
        dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.coregroupId>
            <artifactId>jackson-coreartifactId>
            <version>${version.jackson}version>
        dependency>

        
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-petstoreartifactId>
            <version>2.5.0version>
        dependency>

由于项目框架版本限制，此处只使用2.6版本的SpringFox。另外，根据项目实际情况解决依赖冲突。

添加swagger配置类

import org.springframework.context.annotation.Bean;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Tag;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author yanzy
 * @description api文档配置类
 * @date 2018-03-27 14:55
 * @created by intelliJ IDEA
 */
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig{
    @Bean
    public Docket api() {

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("api") //  组名
                .tags(new Tag("SMR-Services","xxx控制器"),
                        new Tag("Shiro-Services","xxx控制器"))
                .select()  // 选择哪些路径和api会生成document
                  .apis(RequestHandlerSelectors.basePackage("packageName"))//// 对packageName包中的api进行监控
                  .paths(PathSelectors.any())      // regex, ant, any (default), none 格式：PathSelectors.any()
                  .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SDD api navigation")//You application title. Required.
                .description("API Document")//API description. Arbitrary text in CommonMark or HTML.
                .version("1.0.0")//API version. You can use semantic versioning like 1.0.0, or an arbitrary string like 0.99-beta. Required.
                .termsOfServiceUrl("no terms of service")//Link to the page that describes the terms of service.Must be in the URL format.
                .license("Apache 2.0")//Name of the license.
                //.contact(new Contact("yanzy","","[email protected]"))//Contact information: name, email, URL.
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")//A URL to the license description.
                .build();
    }

    @Bean
    UiConfiguration uiConfiguration() {
        UiConfiguration uiConfiguration = new UiConfiguration(null);
        return uiConfiguration;
    }
}

此处特别注意tags的使用，上述问题2中无法点击展开控制器下方法就是由于在控制器的@Api标签中使用tags参数导致的。

SpringMVC的XML配置文件相关配置

    <bean class="dist.dgp.configs.SwaggerConfig"/>
    
    <mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>

具体使用用例

import dist.dgp.bll.impls.smr.SMRMaterialServiceImpl;
import dist.dgp.model.smr.pos.MaterialPo;
import io.swagger.annotations.*;
import lombok.Data;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author yanzy
 * @description
 * @date 2018-04-11 14:42
 * @created by intelliJ IDEA
 */
@RestController
@RequestMapping("materialController")
@Api
@Data
@Slf4j
public class MaterialService {
    @Autowired
    SMRMaterialServiceImpl smrMaterialService;

    @RequestMapping(value = "/create",method = {RequestMethod.POST})
    @ApiOperation(tags = {"SMR-Services"},value = "Material-新建")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "materialPo", value = "资料报告对象", required = true, paramType = "RequestBody", dataType = "MaterialPo")
    })
    @ApiResponses({
            @ApiResponse(code = 200,message = "OK",response = boolean.class),
            @ApiResponse(code = 400,message = "FAULT",response = boolean.class)
    })
    public boolean create(@RequestBody MaterialPo materialPo){
        return this.smrMaterialService.createMaterial(materialPo);
    }

    @RequestMapping(value = "/saveorupdate",method = {RequestMethod.POST})
    @ApiOperation(tags = {"SMR-Services"},value = "Material-保存或更新",notes = "根据\"id\"是否已存在来判断是保存还是更新")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "materialPo", value = "资料报告对象", required = true, paramType = "body", dataType = "MaterialPo")
    })
    public boolean saveorupdate(@RequestBody MaterialPo materialPo){
        return this.smrMaterialService.saveOrUpdateMaterial(materialPo);
    }
}

最终显示结果为：

按照上述过程操作完，你就能得到一个swagger api document了，访问地址如下:
[ip]:[port]/../swagger-ui.html
本篇内容为对springfox的基本使用，细节将在日后慢慢补充。