SpringBoot集成Swagger-UI

1.添加必要的依赖

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

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

注意：尽量使用较新的版本，因为在实际开发过程中，有些api文档中的一些细节控制低版本不支持，比如控制一个实体属性在api文档上不展示。

2.编写对应Swagger的配置类

package com.tufire.seller.config;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger配置类，为所有的controller生成访问的API文档
 * 本地访问地址：http://localhost:{server.port}/swagger-ui.html
 *
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    private static final String CONTROLLER_PACKAGE = "控制层根目录";
    
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("API名称描述").apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage(CONTROLLER_PACKAGE)).paths(PathSelectors.any()).build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("API名称描述").contact(new Contact("", "", "联系人邮箱地址")).version("1.0").build();
    }
}

3.控制层进行定义API接口的各种描述

package com.tufire.seller.api.user;

import com.tufire.common.util.ObjectUtil;
import com.tufire.common.util.Result;
import com.tufire.seller.api.basic.BasicApi;
import com.tufire.seller.query.user.DistrictQuery;
import com.tufire.user.client.DistrictClient;
import com.tufire.user.dto.DistrictDto;
import com.tufire.user.vo.commmon.DistrictVo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@Api(value = "地区相关接口", tags = "地区相关接口")
@RestController
@RequestMapping("/authc/district/")
@Slf4j
public class DistrictApi extends BasicApi {

    @Autowired
    private DistrictClient districtClient;

    @ApiOperation(value = "获取地区信息列表", notes = "获取地区信息列表",produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    @RequestMapping(value = "find_list",method = RequestMethod.POST)
    public Result<List<DistrictVo>> findList(@ModelAttribute DistrictQuery query){
        DistrictDto districtDto = ObjectUtil.source2Target(query, DistrictDto.class);

        return Result.generateSuccess(districtClient.findList(districtDto));
    }
}

4.访问自己的API接口文档

http://localhost:8092/swagger-ui.html#/

5.API通常的界面风格就如上面的效果，有没有更好的界面展示风格呢，答案是肯定的！

在原有项目的基础上增加如下依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.8.7</version>
</dependency>

现在访问如下地址：

http://localhost:8092/doc.html

第4和第5两种方式是兼容的，仅仅是UI展示效果不同。