SpringBoot - SWAGGER2的集成与使用(一)

写在前面

在实际的前后端项目分离开发中，为了便于开发人员的沟通，一般都会构建一份 RESTful API 文档来描述所有的接口信息，但是传统文档不仅编写工作量巨大，且维护不便于更新和维护，为解决这些问题，在项目中使用 Swagger2 来构建在线接口文档，以满足日常开发工作的需要。
SWAGGER官网

SWAGGER2是干什么的？

SWAGGER2是一套基于OAS构建的开源软件框架，可以帮助开发人员设计、构建、记录和使用 RESTful Web 服务，它将代码和文档融为一体，可以完美解决文档编写繁琐、维护不方便等问题。使得开发人员可以将大部分精力集中到业务中，而不是繁杂琐碎的文档中，SWAGGER2包括的组件：

A. Swagger Editor ：基于浏览器的在线编辑器，可以在里面编写 Open API规范，和Markdown类似具有实时预览描述文件的功能。
B. Swagger UI：将OAS呈现为交互式 API 文档，用可视化的方式展示描述文件。
C. Swagger Codegen：将OAS生成为服务器存根和客户端库。通过 Swagger Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。
D. Swagger Inspector：和 Swagger UI 有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。
E. Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 SwaggerHub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

OpenAPI 是什么？

在浏览SWAGGER官网的时候，会看到OpenAPI，那它是什么呢，为什么使用它呢？

Open API 规范(OpenAPI Specification)以前叫做 Swagger 规范，是REST API 的 API 描述格式。OpenAPI 规范（OAS）为 RESTful API 定义了一个与语言无关的标准接口，允许人和计算机发现和理解服务的功能，而无需访问源代码、文档或通过网络流量检查。正确定义后，消费者可以使用最少量的实现逻辑来理解远程服务并与之交互，文档生成工具可以使用 OpenAPI 定义来显示 API。

Springfox是什么？

当我们使用SWAGGER2的时候，经常是如下这样使用的，那Springfox是干什么的呢？

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

Springfox是一个通过扫描代码提取代码中相关信息并生成API文档的工具。API文档的格式不止Swagger的OpenAPI Specification规范，还有RAML、JSONAPI等规范，Springfox的目标同样包括支持这些格式。也就是说springfox-swagger2是Springfox对Swagger的支持。

SWAGGER-UI是什么？

SWAGGER-UI就是接口文档的可视化界面，主要用于展示接口数据、调测试接口和查看接口信息等内容。

①. 依赖引入

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

②. 开启SWAGGER

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	...
}

③. 添加注解

在 Controller上添加相关的 @Api 注解：

（1）@Api，标注在类上用来描述整个 Controller 信息；
（2）@ApiOperation，标注在方法上，用来描述一个方法的基本信息；
（3）@ApiImplicitParam，标注在方法上，用来描述方法的参数。
	其中 paramType 是指方法参数的类型，有如下可选值：
	path：  参数获取方式为 @PathVariable
	query： 参数获取方式为 @RequestParam
	header：参数获取方式为 @RequestHeader
	body
	form
（4）如果有多个参数，可以将多个参数的 @ApiImplicitParam 注解放到 @ApiImplicitParams 中；
（5）@ApiResponse 是对响应结果的描述。code 表示响应码，message 为相应的描述信息，
	如果有多个 @ApiResponse，则放在一个 @ApiResponses 中；
（6）@ApiIgnore 注解表示不对某个接口生成文档。

@RestController
@RequestMapping("/advert")
@Api(value = "广告管理", description = "提供对广告对象的增删改查")
public class SysAdvertController extends BaseController {
    @Autowired
    private ISysAdvertService advertService;

    @Autowired
    private RemoteFileService remoteFileService;

    /**
     * 查询广告信息列表
     */
    @ApiOperation(value = "查询广告信息列表", notes = "根据不同的参数获取广告信息列表")
    @PreAuthorize(hasPermi = "system:advert:list")
    @GetMapping("/list")
    public TableDataInfo list(SysAdvert advert) {
        startPage();
        List<SysAdvert> list = advertService.selectAdvertList(advert);
        return getDataTable(list);
    }

    /**
     * 导出广告信息列表
     */
    @ApiOperation(value = "导出广告信息列表", notes = "根据不同的参数导出广告信息列表")
    @PreAuthorize(hasPermi = "system:advert:export")
    @Log(title = "广告信息", businessType = BusinessType.EXPORT)
    @PostMapping("/export")
    public void export(HttpServletResponse response, SysAdvert advert) throws IOException {
        List<SysAdvert> list = advertService.selectAdvertList(advert);
        ExcelUtil<SysAdvert> util = new ExcelUtil<SysAdvert>(SysAdvert.class);
        util.exportExcel(response, list, "advert");
    }

    /**
     * 获取广告信息详细信息
     */
    @ApiOperation(value = "根据ID获取广告信息对象", notes = "根据ID获取广告信息对象")
    @PreAuthorize(hasPermi = "system:advert:query")
    @GetMapping(value = "/{advertId}")
    public AjaxResult getInfo(@PathVariable("advertId") Long advertId) {
        return AjaxResult.success(advertService.selectAdvertById(advertId));
    }

    /**
     * 新增广告信息
     */
    @ApiOperation(value = "新增广告信息对象", notes = "新增广告信息对象")
    @PreAuthorize(hasPermi = "system:advert:add")
    @Log(title = "广告信息", businessType = BusinessType.INSERT)
    @PostMapping
    public AjaxResult add(@RequestBody SysAdvert advert) {
        return toAjax(advertService.insertAdvert(advert));
    }

    /**
     * 修改广告信息
     */
    @ApiOperation(value = "修改广告信息对象", notes = "修改广告信息对象")
    @PreAuthorize(hasPermi = "system:advert:edit")
    @Log(title = "广告信息", businessType = BusinessType.UPDATE)
    @PutMapping
    public AjaxResult edit(@RequestBody SysAdvert advert) {
        return toAjax(advertService.updateAdvert(advert));
    }

    /**
     * 删除广告信息
     */
    @ApiOperation(value = "批量删除广告信息对象", notes = "根据IDS批量删除广告信息对象")
    @PreAuthorize(hasPermi = "system:advert:remove")
    @Log(title = "广告信息", businessType = BusinessType.DELETE)
    @DeleteMapping("/{advertIds}")
    public AjaxResult remove(@PathVariable Long[] advertIds) {
        return toAjax(advertService.deleteAdvertByIds(advertIds));
    }

    /**
     * 广告图片上传
     */
    @PreAuthorize(hasPermi = "system:advert:edit")
    @Log(title = "上传广告图片", businessType = BusinessType.UPDATE)
    @PostMapping("/upload")
    @ApiOperation(value = "上传广告图片", notes = "上传广告图片")
    public AjaxResult avatar(@RequestParam("img") MultipartFile file) throws IOException {
        if (!file.isEmpty()) {
            R<SysFile> img = remoteFileService.upload(file);
            if (StringUtils.isNull(img) || StringUtils.isNull(img.getData())) {
                return AjaxResult.error("文件服务异常，请联系管理员");
            }
            String url = img.getData().getUrl();
            if (null != url) {
                AjaxResult ajax = AjaxResult.success();
                ajax.put("imgUrl", url);
                return ajax;
            }
        }
        return AjaxResult.error("上传图片异常");
    }
}

在实体对象上添加相关的 @ApiModel 注解：

@ApiModel(value = "广告实体对象", description = "广告信息描述对象")
public class SysAdvert extends BaseEntity {
    private static final long serialVersionUID = 1L;

    /**
     * 主键
     */
    @ApiModelProperty(value = "广告ID")
    private Long advertId;

    /**
     * 广告标题
     */
    @Excel(name = "广告标题")
    @ApiModelProperty(value = "广告标题")
    private String advertTitle;

    /**
     * 广告分类
     */
    @Excel(name = "广告分类")
    @ApiModelProperty(value = "广告分类")
    private Long advertCategory;
}

④. 查看文档

启动服务并查看文档：http://localhost:8080/swagger-ui.html