Swagger介绍及使用

一、简介
一般我们在对接前后端的时候，都需要提供相应的接口文档。对于后端来说，编写接口文档即费时费力，还会经常因为没有及时更新，导致前端对接时出现实际接口与文档不一致。而且手写接口文档还容易出错，而swagger很好的解决了这个痛点。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。可用于：1.接口的文档在线自动生成、2.功能测试。

二、使用
1.maven导入Swagger

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

2.创建Swagger2配置类

/**
 * Copyright (c) 2018 王牌后台 All rights reserved.
 *
 * https://www.wangpai.io
 *
 * 版权所有，侵权必究！
 */

package io.wangpai.common.config;

import io.wangpai.common.constant.Constant;
import io.swagger.annotations.ApiOperation;
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.ApiKey;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.List;

import static com.google.common.collect.Lists.newArrayList;

/**
 * Swagger配置
 *
 * @author Mark sunlightcs@gmail.com
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig{

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //加了ApiOperation注解的类，生成接口文档
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            //包下的类，生成接口文档
            //.apis(RequestHandlerSelectors.basePackage("io.wangpai.modules.job.controller"))
            .paths(PathSelectors.any())
            .build()
            .directModelSubstitute(java.util.Date.class, String.class)
            .securitySchemes(security());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("王牌Api")
            .description("wangpai-admin文档")
            .termsOfServiceUrl("https://www.wgame.io")
            .version("2.0.0")
            .build();
    }

    private List<ApiKey> security() {
        return newArrayList(
            new ApiKey(Constant.TOKEN_HEADER, Constant.TOKEN_HEADER, "header")
        );
    }
}

docket() 方法创建Docket的Bean对象，apiInfo()则是创建ApiInfo的基本信息。

3.注解说明

@Api : 用在类上，说明该类的主要作用。

@ApiOperation：用在方法上，给API增加方法说明。

@ApiImplicitParams : 用在方法上，包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应。

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

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

@ApiModelProperty：描述一个model的属性

例子：

package io.wangpai.modules.ace.controller;

import io.wangpai.common.annotation.DataFilter;
import io.wangpai.common.annotation.LogOperation;
import io.wangpai.common.constant.Constant;
import io.wangpai.common.page.PageData;
import io.wangpai.common.utils.ExcelUtils;
import io.wangpai.common.utils.Result;
import io.wangpai.common.validator.AssertUtils;
import io.wangpai.common.validator.ValidatorUtils;
import io.wangpai.common.validator.group.AddGroup;
import io.wangpai.common.validator.group.DefaultGroup;
import io.wangpai.common.validator.group.UpdateGroup;
import io.wangpai.modules.ace.dto.AppVersionDTO;
import io.wangpai.modules.ace.excel.AppVersionExcel;
import io.wangpai.modules.ace.service.AppVersionService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.wangpai.modules.sys.dto.SysDeptDTO;
import io.wangpai.modules.sys.service.SysDeptService;
import org.apache.shiro.authz.annotation.RequiresPermissions;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

import javax.servlet.http.HttpServletResponse;
import java.util.List;
import java.util.Map;


/**
 * 版本表
 */
@RestController
@RequestMapping("ace/appversion")
@Api(tags="版本表")
public class AppVersionController {
    @Autowired
    private AppVersionService appVersionService;
    @Autowired
    private SysDeptService sysDeptService;

    @GetMapping("page")
    @ApiOperation("分页")
    @ApiImplicitParams({
        @ApiImplicitParam(name = Constant.PAGE, value = "当前页码，从1开始", paramType = "query", required = true, dataType="int") ,
        @ApiImplicitParam(name = Constant.LIMIT, value = "每页显示记录数", paramType = "query",required = true, dataType="int") ,
        @ApiImplicitParam(name = Constant.ORDER_FIELD, value = "排序字段", paramType = "query", dataType="String") ,
        @ApiImplicitParam(name = Constant.ORDER, value = "排序方式，可选值(asc、desc)", paramType = "query", dataType="String")
    })
    @RequiresPermissions("ace:appversion:page")
    @DataFilter
    public Result<PageData<AppVersionDTO>> page(@ApiIgnore @RequestParam Map<String, Object> params){
        PageData<AppVersionDTO> page = appVersionService.page(params);
        page.getList().forEach(dto -> {
            SysDeptDTO sysDeptDTO= sysDeptService.get(dto.getDeptId());
            if(sysDeptDTO!=null) {
                dto.setDeptName(sysDeptDTO.getName());
            }
        });
        return new Result<PageData<AppVersionDTO>>().ok(page);
    }

    @GetMapping("{id}")
    @ApiOperation("信息")
    @RequiresPermissions("ace:appversion:info")
    public Result<AppVersionDTO> get(@PathVariable("id") Long id){
        AppVersionDTO data = appVersionService.get(id);
        SysDeptDTO sysDeptDTO= sysDeptService.get(data.getDeptId());
        data.setDeptName(sysDeptDTO.getName());
        return new Result<AppVersionDTO>().ok(data);
    }

    @PostMapping
    @ApiOperation("保存")
    @LogOperation("保存")
    @RequiresPermissions("ace:appversion:save")
    public Result save(@RequestBody AppVersionDTO dto){
        //效验数据
        ValidatorUtils.validateEntity(dto, AddGroup.class, DefaultGroup.class);

        appVersionService.save(dto);

        return new Result();
    }

    @PutMapping
    @ApiOperation("修改")
    @LogOperation("修改")
    @RequiresPermissions("ace:appversion:update")
    public Result update(@RequestBody AppVersionDTO dto){
        //效验数据
        ValidatorUtils.validateEntity(dto, UpdateGroup.class, DefaultGroup.class);

        appVersionService.update(dto);

        return new Result();
    }

    @DeleteMapping
    @ApiOperation("删除")
    @LogOperation("删除")
    @RequiresPermissions("ace:appversion:delete")
    public Result delete(@RequestBody Long[] ids){
        //效验数据
        AssertUtils.isArrayEmpty(ids, "id");

        appVersionService.delete(ids);

        return new Result();
    }

    @GetMapping("export")
    @ApiOperation("导出")
    @LogOperation("导出")
    @RequiresPermissions("ace:appversion:export")
    public void export(@ApiIgnore @RequestParam Map<String, Object> params, HttpServletResponse response) throws Exception {
        List<AppVersionDTO> list = appVersionService.list(params);

        ExcelUtils.exportExcelToTarget(response, null, list, AppVersionExcel.class);
    }

}

4.测试登录 localhost:8080/swagger-ui.html

API 操作测试，修改

更多内容请关注微信公众号“外里科技”