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>

配置类

package com.swaggerTest;
 
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;
 
/**
 * Swagger2配置类
 * 在与spring boot集成时，放在与Application.java同级的目录下。
 * 通过@Configuration注解，让Spring来加载该类配置。
 * 再通过@EnableSwagger2注解来启用Swagger2。
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * 
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swaggerTest.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多请关注http://www.baidu.com")
                .termsOfServiceUrl("http://www.baidu.com")
                .contact("sunf")
                .version("1.0")
                .build();
    }
}

添加文档内容

在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，描述的主要来源是函数的命名，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。

Swagger使用的注解及其说明：

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

value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

@ApiOperation：注解来给API增加方法说明。

value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
response	返回的对象
hidden	配置为true 将在文档中隐藏
httpMethod	"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code	http的状态码 默认 200
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
responseContainer	这些对象是有效的 "List", "Set" or "Map".，其他无效
authorizations	高级特性认证时配置
extensions	扩展属性

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

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

• paramType：参数放在哪个地方

• name：参数代表的含义

• value：参数名称

• dataType： 参数类型，有String/int，无用

• required ： 是否必要

• defaultValue：参数的默认值

@ApiResponses：用于表示一组响应

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

l code：数字，例如400

l message：信息，例如"请求参数没填好"

l response：抛出异常的类

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModelProperty**：描述一个model的属性

例子

/**
 * @Auther: wyq
 * @Date: 2018/12/29 14:50
 */
@RestController
@Api(value = "电影Controller", tags = { "电影访问接口" })
@RequestMapping("/film")
public class FilmController {
​
    @Autowired
    private FilmService filmService;
​
    /**
     * 添加一个电影数据
     *
     * @param
     * @return
     */
    @ApiOperation(value = "添加一部电影")
    @PostMapping("/addFilm")
    @ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失败"),
            @ApiResponse(code = 1002, response = Film.class,message = "缺少参数") })
    public ResultModel addFilm(@ApiParam("电影名称") @RequestParam("filmName") String filmName,
                               @ApiParam(value = "分数", allowEmptyValue = true) @RequestParam("score") Short score,
                               @ApiParam("发布时间") @RequestParam(value = "publishTime",required = false) String publishTime,
                               @ApiParam("创建者id") @RequestParam("creatorId") Long creatorId) {
​
        if (Objects.isNull(filmName) || Objects.isNull(score) || Objects.isNull(publishTime) || StringUtils
                .isEmpty(creatorId)) {
            return new ResultModel(ResultModel.failed, "参数错误");
        }
        Film filmPOM = new Film();
        filmPOM.setFilmName(filmName);
        filmPOM.setScore(score);
        DateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd");
        Date publishTimeDate = null;
        try {
            publishTimeDate = simpleDateFormat.parse(publishTime);
        } catch (Exception ex) {
            ex.printStackTrace();
        }
        filmPOM.setPublishTime(publishTimeDate);
        filmPOM.setCreatorId(creatorId);
        Boolean result = filmService.addFilm(filmPOM);
        if (result) {
            return new ResultModel(CommonConstants.SUCCESSMSG);
        }
        return new ResultModel(CommonConstants.FAILD_MSG);
    }
​
    /**
     * 根据电影名字获取电影
     *
     * @param fileName
     * @return
     */
    @GetMapping("/getFilms")
    @ApiOperation(value = "根据名字获取电影")
    @ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失败"),
            @ApiResponse(code = 1002, message = "缺少参数") })
    public ResultModel getFilmsByName(@ApiParam("电影名称") @RequestParam("fileName") String fileName) {
        if (StringUtils.isEmpty(fileName)) {
            return CommonConstants.getErrorResultModel();
        }
​
        List<Film> films = filmService.getFilmByName(fileName);
        if (!CollectionUtils.isEmpty(films)) {
            return new ResultModel(films);
        }
        return CommonConstants.getErrorResultModel();
​
    }
​
    /**
     * 根据电影名更新
     *
     * @return
     */
    @PostMapping("/updateScore")
    @ApiOperation(value = "根据电影名修改分数")
    @ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失败"),
            @ApiResponse(code = 1002, message = "缺少参数") })
    public ResultModel updateFilmScore(@ApiParam("电影名称") @RequestParam("fileName") String fileName,
                                       @ApiParam("分数") @RequestParam("score") Short score) {
        if (StringUtils.isEmpty(fileName) || Objects.isNull(score)) {
            return CommonConstants.getErrorResultModel();
        }
​
        filmService.updateScoreByName(fileName, score);
        return CommonConstants.getSuccessResultModel();
    }
​
    /**
     * 根据电影名删除电影
     *
     * @param request
     * @return
     */
    @PostMapping("/delFilm")
    @ApiOperation(value = "根据电影名删除电影")
    @ApiImplicitParams({ @ApiImplicitParam(name = "filmName",
            value = "电影名",
            dataType = "String",
            paramType = "query",
            required = true), @ApiImplicitParam(name = "id", value = "电影id", dataType = "int", paramType = "query") })
    public ResultModel deleteFilmByNameOrId(HttpServletRequest request) {
        //电影名
        String filmName = request.getParameter("filmName");
        //电影id
        Long filmId = Long.parseLong(request.getParameter("id"));
​
        filmService.deleteFilmOrId(filmName,filmId);
​
​
        return CommonConstants.getSuccessResultModel();
    }
​
    /**
     * 根据id获取电影
     *
     * @param id
     * @return
     */
    @PostMapping("/{id}")
    @ApiOperation("根据id获取电影")
    @ApiImplicitParam(name = "id", value = "电影id", dataType = "long", paramType = "path", required = true)
    public ResultModel getFilmById(@PathVariable Long id) {
​
        if (Objects.isNull(id)) {
            return CommonConstants.getLessParamResultModel();
        }
        Film film = filmService.getFilmById(id);
        if (Objects.nonNull(film)) {
            return new ResultModel(film);
        }
        return CommonConstants.getErrorResultModel();
    }
​
    /**
     * 修改整个电影
     *
     * @param film
     * @return
     */
    @PostMapping("/insertFilm")
    @ApiOperation("插入一部电影")
    public ResultModel insertFilm(@ApiParam("电影实体对象") @RequestBody Film film) {
        if (Objects.isNull(film)) {
            return CommonConstants.getLessParamResultModel();
        }
        Boolean isSuccess = filmService.insertFilm(film);
        if (isSuccess) {
            return CommonConstants.getSuccessResultModel();
        }
        return CommonConstants.getErrorResultModel();
    }
}