SpringBoot集成Swagger2生成Api文档

SpringBoot整合Swagger2

一、添加Swagger2 pom依赖文件

1、此处为根目录下pom依赖

  2.4.0

      io.springfox
      springfox-swagger-ui
      ${swagger.version}


      io.springfox
      springfox-swagger2
      ${swagger.version}

2、当前工程下依赖

   io.springfox
   springfox-swagger-ui


   io.springfox
   springfox-swagger2

二、新建Swagger2配置类

下面为示例：

package com.fanxf;

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;

/**
 * @author fanxf
 * @date 2018/2/28 10:10
 */
@EnableSwagger2
@Configuration
public class Swagger {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.fanxf.service.demo.controller")) //当前包路径
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("api文档") //页面标题
                .contact(new Contact("fanxf","www.fanxf.com","[email protected]")) //创建人
                .version("1.0") //版本号
                .description("api文档") //描述
                .build();
    }
}

讲解：1、@Configuration注解，让Spring来加载该类配置，

          2、@EnableSwagger2注解来启用Swagger2。

          3、通过buildDocket函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。      

          4、select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径

                来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore注解的API）。

三、controller编写

代码如下：

package com.fanxf.service.demo.controller;

import com.fanxf.ColorRespDto;
import com.fanxf.domain.Style;
import com.fanxf.service.StyleService;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.apache.commons.lang.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;
import java.util.List;

/**
 * @author fanxf
 * @date 2018/2/6 16:13
 */
@RestController
@RequestMapping("/demo")
public class ColorController {

    @Autowired
    private StyleService styleService;

    @ApiOperation(value = "查询车辆颜色", notes = "根据车型id查询所有颜色")
    @ApiImplicitParam(name = "id", value = "车型id", dataType = "String", paramType = "path")
    @GetMapping("/color/{id}")
    public ColorRespDto getList(@PathVariable String id) {
        Style style = styleService.selectById(id);
    if (null == style) {
        return null;
    }
        List list = new ArrayList();
        String[] str = style.getColor().split(".");
        for (String color : str) {
            list.add(color);
        }
        ColorRespDto dto = new ColorRespDto();
        dto.setColor(list);
        return dto;
    }
}

讲解：1、@ApiOperation：用在方法上，说明方法的作用，标注在具体请求上，value和notes的作用差不多，都是对请求进行

                 说明

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

             3、@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

　　            paramType：参数放在哪个地方

　　            header 请求参数的获取：@RequestHeader

　　            query 请求参数的获取：@RequestParam

　　            path（用于restful接口） 请求参数的获取：@PathVariable

　　            body（不常用）

　　            form（不常用）

　　            name：参数名

　　            dataType：参数类型

　　            required：参数是否必须传

　　            value：参数的意思

　　            defaultValue：参数的默认值

完成controller后启动springboot

启动成功后打开浏览器输入http://localhost:1010/swagger-ui.html（1010为当前启功端口号），就能看到前文所展示的RESTful API的页面。 

如图：

可以看到其中的controller

点击然后进行访问：