Springboot集成Swagger2生成API文档

Swagger简介：

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger 的优势：

支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

1. 创建Springboot项目

2. 添加Maven依赖：

<!--Swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
 <!-- END Swagger2 -->

3. 编写配置类

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;

/**
 * Swagger2 配置类
 * @Configuration 让 Spring 容器加载该配置类
 * @EnableSwagger2 用于启动 swagger2 , springboot启动类也需要加
 */

@Configuration
@EnableSwagger2
public class Swagger2Config {

    /**
     * swagger2 启动后，通过createRestApi函数创建Docket的Bean，
     * apiInfo() 用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。
     * select() 函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
     * @return
     */

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)// 指定api类型为swagger2
                .apiInfo(apiInfo())// 用于定义api文档汇总信息,下面的apiInfo()
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.springboot_jpa"))//api接口包扫描路径
                .paths(PathSelectors.any())// 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Springboot 中使用Swagger2构建RESTful APIs")//设置文档的标题
                .description("springboot学习")// 设置文档的描述
                .contact(new Contact("huangwc",
                        "http://www.baidu.com",
                        "huangwencon@foxmail.com")) // 联系人信息
                .termsOfServiceUrl("http://www.baidu.com")// 网站地址
                .version("2.0")// 文档版本号
                .build();
    }

}

4. 注释启动类：@EnableSwagger2

@SpringBootApplication
@EnableSwagger2
public class SpringbootJpaApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringbootJpaApplication.class, args);
    }

}

5. API 接口编写并生成文档

/*
@Api：修饰整个类，描述Controller的作用
        tags="说明该类的作用，可以在UI界面上看到的注解，如果tags多个值，会生成多个list"
        value="该参数没什么意义，在UI界面上也看不到，所以不需要配置"
@ApiOperation：用在请求的方法上，说明方法的用途、作用
        value="说明方法的用途、作用"
        notes="方法的备注说明"
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表
 **/

@Controller
@Api(value = "用户接口",tags = {"用户操作接口"})
public class UserController {

    @Autowired
    private CarategyRepository carategyRepository;

    @Autowired
    private NewsRepository newsRepository;

    @RequestMapping("gotocarategy")
    public String gotoaddcarategy(){
        return "user/addcarategy";
    }
    
    @ApiOperation(value = "增加carategy",notes = "增加carategy")
    /*新增carategy*/
    @RequestMapping("/addcarategy")
    public String add(@RequestParam(name = "carategy") String carategy){
        Carategy carategy1 = new Carategy();
        carategy1.setCarategy(carategy);
        System.out.println(carategy1.getCarategy());
        String str = carategy1.getCarategy();
        carategyRepository.addCarategy(str);
        return "forward:getallcarategy";
    }

    @ApiOperation(value = "用于方法描述query",notes = "这是用来说明该方法，提示内容")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "data",value = "字符串数据",dataType = "String",paramType = "path",example = "白居易",required = true,defaultValue = "白居易"),
            @ApiImplicitParam(name = "i",value = "int类型",dataType = "int",paramType = "path",example = "666",required = true,defaultValue = "666")
    })
    /*查询所有carategy类型，返回数据给新闻增加page*/
    @RequestMapping("getallcarategy")
    public String findallcarategy(Model model){
        List<Carategy> list = carategyRepository.findAll();
        model.addAttribute("carategylist",list);
        return "user/addnews";
    }
}

启动Springboot项目，访问http://ip:端口/swagger-ui.html就可以看到swagger2生成的文档了。