SpringBoot集成Swagger构建API文档

Meven配置

<!-- Swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

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

注册组件

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    @Bean
    public Docket accessToken() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//配置说明
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zsdk.controller"))//拦截的包
                .paths(PathSelectors.any())//拦截的接口路径,也可以指定，如：regex("/v1/user/.*")
                .build();

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot利用Swagger构建API文档")
                .description("接口文档")
                .termsOfServiceUrl("http://www.kris.com")
                .contact(new Contact("kris", "http://www.zsdk.com", "123456789@ qq.com"))//联系
                .version("1.0")
                .build();
    }

}

配置静态文件映射

/**
 * 拦截器配置
 *
 * @author kris
 * @create 2018-01-08 11:45
 */
@Configuration
public class ServletContextConfig extends WebMvcConfigurationSupport {

    /**
     *  发现如果继承了WebMvcConfigurationSupport，则在yml中配置的相关内容会失效。
     *  需要重新指定静态资源
     *  @param registry
     * 
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }

    /**
     * 配置servlet处理
     */
    @Override
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
        configurer.enable();
    }
}

编写controller

/**
 * @author kris
 * @create 2017-10-11 17:45
 */
@RestController
@RequestMapping("/v1/basic")
public class BasicController extends WebApiController{

    @Autowired
    private CustomConfigService mCustomConfigService;   

    @PostMapping("/init")
    public WebApiResult init(@RequestBody InitReqModel model) {


        //获取初始化配置，如：客服信息、官网
        CustomServiceConfig serviceConfig = mCustomConfigService.findCustomConfig(model.getAppId(),model.getChannelId());

        return apiSuccess(serviceConfig);
    }
} 

查看效果

1. 启动应用，访问地址：http://localhost:8080/swagger-ui.html
2. 效果图
   
   

自定义（注解的使用）

@ApiIgnore
忽略暴露的 api

@ApiOperation(value = “查找”, notes = “根据用户 ID 查找用户”)
添加说明

其他注解：

@Api ：用在类上，说明该类的作用

@ApiImplicitParams ：用在方法上包含一组参数说明

@ApiResponses ：用于表示一组响应

@ApiResponse ：用在@ApiResponses 中，一般用于表达一个错误的响应信息

code：数字，例如 400
message：信息，例如”请求参数没填好”
response：抛出异常的类

@ApiModel ：描述一个 Model 的信息（这种一般用在 post 创建的时候，使用@RequestBody 这样的场
景，请求参数无法使用@ApiImplicitParam 注解进行描述的时候）

@ApiModelProperty ：描述一个 model 的属性