Swagger配置与使用

Swagger作用：

自动生成javaAPI，避免开发过程中接口文档更新不及时。

 一.导入依赖：

<!--swagger包-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>
<!--swagger包结束-->

二.Swagger首页的配置：

创建一个SwaggerConfig类，通过@Configuration托管给spring，然后通过@EnableSwagger2 注解开启Swagger，Config类大部分都是固定的，没什么改变的需要：

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

/**
 * @time 14:51
 * @desc Swagger配置类，该类里面的应该是固定的，主要用来设置文档的主题信息，比如文档的大标题，副标题，公司名
 * 等
 */
@Configuration//托管spring
@EnableSwagger2//开启swagger功能
public class SwaggerConfig {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi(){
        //版本类型是swagger2
        return new Docket(DocumentationType.SWAGGER_2)
                //通过调用自定义方法apiInfo，获得文档的主要信息
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zy100.controller"))//扫描该包下面的API注解
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("使用Swagger2 构建RESTful APIS - zy") //接口管理文档首页显示
                .description("zy - Swagger使用演示")//API的描述
                .termsOfServiceUrl("www.footmark.top")//网站url等
                .version("1.0")
                .build();
    }
}

三.Swagger的Controller示例

在需要生成接口文档的Controller中加上@API注解，类中需要生成接口的方法上加上@ApiOperation注解：

package com.zy100.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.Date;
import java.util.HashMap;
import java.util.Map;

/**
 * @desc 配合swagger创建一个Controller，演示方便不再创建service层
 */
@RestController
@Api("用户模块API文档")//注解api说明该类需要生成api文档
public class UserController {
    /**
     * 该类中
     * @param map 类似于一个user对象
     * key就是对象的属性
     * value就是对象的属性值
     *   ------------------------
     * 属性 id name birthday
     * @return
     */
    //正常业务整添加是对象，前台传JSON对象，在此使用map代替
    @PostMapping("/user")//如果使用swagger自动生成接口文档，一定要加上请求类型，不然会导致swagger把所有请求都会生成一下
    @ApiOperation("添加用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "map",//参数名字
                    value = "这是一个添加的对象",//参数的描述
                    required = true,//是否必须传参数，true是
                    paramType = "body")//参数类型 body代表json
    })
    public Map add(@RequestBody Map map){
        return map;
    }
    //根据id删除数据。
    @DeleteMapping("/user/{id}")
    @ApiOperation("删除用户")//API中说明的该类的作用
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",//参数名字
                    value = "用户id",//参数的描述
                    required = true,//是否必须传参数，true是
                    paramType = "path",//参数类型 path代表路径参数
                    dataType = "int")//参数类型 int
    })
    public String deltete(@PathVariable int id){
        return "{code:200,msg:删除"+id+"成功}";
    }
    //根据传入的对象信息进行更新
    @PutMapping("/user")
    @ApiOperation("更新用户")//API中说明的该类的作用
    @ApiImplicitParams({
            @ApiImplicitParam(name = "map",//参数名字
                    value = "更新的用户",//参数的描述
                    required = true,//是否必须传参数，true是
                    paramType = "body",//参数类型 body
                    dataType = "map")//参数类型 int
    })
    public Map update(@RequestBody Map map){
        return map;
    }
    @GetMapping("/user/{id}")
    @ApiOperation("查询永不用户")//API中说明的该类的作用
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",//参数名字
                    value = "查询的用户id",//参数的描述
                    required = true,//是否必须传参数，true是
                    paramType = "path",//参数类型 body
                    dataType = "int")//参数类型 int
    })
    public Map getOne(@PathVariable int id){
        Map<String,Object> map = new HashMap<>();
        map.put("id",id);
        map.put("name","张三");
        map.put("birthday",new Date());
        return map;
    }
}