Swagger使用体验

最近的一个项目是前后端分离开发，自己只负责后端业务逻辑编写与设计。由于之前经历的项目大多数自己全权负责，所以在给前端工程师提供接口介绍时，采用的还是是编写接口文档。

在使用文档记录的这段时间，出现了诸多不便：

1.实时性：更改接口参数以及地址等信息时，需要修改文档；

2.准确性：不可避免的出现了小部分参数遗漏、方法名以及参数名错误等情况，所造成的访问请求失败；

3.文档规范：自己编写文档时，贪图省事，忽略了很多细节；比如上述文档中未表明参数必填/非必填、未表明返回值格式。

这些问题在我整合了Swagger之后都迎刃而解

Swagger搭建完成后，随着服务的启动可以访问 服务地址/swagger-ui.html 可查看目前所有Controller下接口信息；

在接口详情中，我们可以看到具体参数名称、格式。另外Swagger页面提供了接口测试功能，无需我们使用第三方工具PostMan/PostWoman网站或者自己编写测试请求来测试接口；

返回结果信息全面，自动格式化更加直观。与传统方法编写接口文档相比Swagger在实时性、准确性以及文档规范三个方面都有过之而无不及，更加重要的是它配置简单，配置完成之后大大提高工作效率。

以下是我自己整理的配置流程：

1.使用Maven引入所需Jar

<!-- Swagger -->
    <dependency>
        <groupId>com.spring4all</groupId>
        <artifactId>swagger-spring-boot-starter</artifactId>
        <version>1.7.1.RELEASE</version>
    </dependency>

2.在Application上添加注解，开启Swagger

@SpringBootApplication
@EnableSwagger2Doc
@MapperScan("com.devin.inventory.mapper")
public class InventoryApplication {
    public static void main(String[] args) {
        SpringApplication.run(InventoryApplication.class, args);
    }
}

3.Controller内添加注解，并修改默认值

@RestController
@Api(tags={"角色管理"})
@RequestMapping("/sys-role")
public class SysRoleController {
    @Resource
    ISysRoleService service;
    @Resource
    ISysNumberService numberService;
    @ApiOperation(value = "获取所有角色")
    @PostMapping("getRole")
    public CommonResult getRole() {
        return new CommonResult(200, "success", service.list());
    }
}

4.访问 /swagger-ui.html 查看效果

注： 启动失败且异常表现为：

Caused by: java.lang.ClassNotFoundException: javax.validation.constraints.Min

引入validation jar包即可

<dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
</dependency>