1 为什么是使用 swagger?
1-1 当后台开发人员开发好接口, 是不是还要重新书写一份接口文档提给前端人员, 当然对于程序员最不喜欢的就是书写文档 (当然文档是必须的, 有利于项目的维护)
1-2 当后台人员开发接口, 当然后台开发者也是需要测试好接口是否可用, 当参数少的时候测试还不是很麻烦, 当参数有十多个的时候, 就需要后台开发者一个一个的拼接参数, 很是耗时间而且还容易写错参数名, swagger 就很好解决了这个问题 (当然也是可以借助其他插件: rest-client 工具, PostMan)
2 搭建环境: window,spring boot,swaager,maven
3 开始搭建: 搭建过程很简单, 有关于 swagger 注解本文不详细叙述, 其实只使用常用的几个注解就 ok 了 (@ApiOperation,@EnableSwagger2,@Api)
3-1 导入必须 jar 包 , 修改 pom.xml
- <dependency>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter-test</artifactId>
- <scope>test</scope>
- </dependency>
- <dependency>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter-web</artifactId>
- <version>RELEASE</version>
- </dependency>
- <dependency>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter-aop</artifactId>
- </dependency>
- <!-- swagger -->
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger-ui</artifactId>
- <version> 2.6.0</version>
- </dependency>
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger2</artifactId>
- <version> 2.6.0</version>
- </dependency>
- <!-- swagger end -->
3-2 配置 swagger
- @Configuration
- @EnableSwagger2 //swagger 注解
- public class SwaggerConfig {
- @Bean
- public Docket allInterface() {
- return new Docket(DocumentationType.SWAGGER_2).groupName("AllInterface(所有接口)")// 定义组
- .select() // 选择那些路径和 api 会生成 document
- .apis(RequestHandlerSelectors.basePackage("com.lishun.controller")) // 拦截的包路径
- .paths(regex("/.*"))// 拦截的接口路径
- .build() // 创建
- .apiInfo(apiInfo())// 配置说明
- .tags(new Tag("index", "起始页"), getTags());
- }
- /**
- * @Description: 这里可以指定其他 tag(对应 controller 的 @Api 注解的 tags 属性值)
- * @author lishun
- * @date 2018/2/28
- * @param []
- * @return springfox.documentation.service.Tag[]
- */
- private Tag[] getTags() {
- Tag[] tags = { new Tag("login", "登录相关") };
- return tags;
- }
- private ApiInfo apiInfo() {
- return new ApiInfoBuilder()//
- .title("swagger api 文档")// 标题
- .description("swagger api 文档")// 描述
- .termsOfServiceUrl("")//
- .contact(new Contact("","", ""))// 联系
- .version("1.0")// 版本
- .build();
- }
- }
3-3 统一所有接口返回值 (便于前端人员开发, 和统一处理 controller 异常)
- public class ResultBean<T> implements Serializable {
- /* 提示信息 */
- public String message = "";
- /* 状态码 */
- public Integer code;
- /* 总页数 */
- private long totalPage;
- /* 页容量 */
- private int pages;
- /* 页码 */
- private int pageNum;
- /* 返回实体信息 */
- private T resultData;
- /* 返回集合实体信息 */
- private List<T> resultDataList;
- public ResultBean() {
- }
- public ResultBean(List<T> resultData, long totalPage, int pages, int pageNum) {
- this.resultDataList = resultData;
- this.totalPage = totalPage;
- this.pages = pages;
- this.pageNum = pageNum;
- }
- public ResultBean(T resultData) {
- this.resultData = resultData;
- }
- public void setMessage(String message) {
- this.message = message;
- }
- public long getTotalPage() {
- return totalPage;
- }
- public void setTotalPage(long totalPage) {
- this.totalPage = totalPage;
- }
- public int getPages() {
- return pages;
- }
- public void setPages(int pages) {
- this.pages = pages;
- }
- public int getPageNum() {
- return pageNum;
- }
- public void setPageNum(int pageNum) {
- this.pageNum = pageNum;
- }
- public List<T> getResultDataList() {
- return resultDataList;
- }
- public void setResultDataList(List<T> resultDataList) {
- this.resultDataList = resultDataList;
- }
- public void setMessage(String message, Object... args) {
- this.message = String.format(message, args);
- }
- public String getMessage() {
- return message;
- }
- public void setResultData(T resultData) {
- this.resultData = resultData;
- }
- public T getResultData() {
- return this.resultData;
- }
- public Integer getCode() {
- return code;
- }
- public void setCode(Integer code) {
- this.code = code;
- }
- public <T> void setResultBean(Integer code, String message,
- Object... mesaageFormatArgs) {
- setCode(code);
- setMessage(message, mesaageFormatArgs);
- }
- }
3-4 统一处理 controller 异常
- /**
- * @author lishun
- * @Description: 控制器 aop 拦截
- * @date 2017/10/27
- */
- @Component
- @Aspect
- public class ControllerAspect {
- @Pointcut("execution(public com.lishun.result.ResultBean com.lishun.controller.*.*(..))")
- public void dataSource(){};
- @Around("dataSource()")
- public Object doAround(ProceedingJoinPoint proceedingJoinPoint) throws Throwable {
- ResultBean result = null;
- try {
- result = (ResultBean<?>)proceedingJoinPoint.proceed();
- } catch (Exception e) {
- result = new ResultBean();
- result.setCode(ResultCode.FAILED);
- result.setMessage(e.getMessage());
- e.printStackTrace();
- }
- return result;
- }
- }
- 3-4 contrlloer
- @RestController
- @Api(tags = { "index" })
- public class IndexController {
- @GetMapping("/index/{id}")
- @ApiOperation(value = "findByOne", notes = "获取一条数据")
- public ResultBean<String> findByOne(@PathVariable(value = "id") String id) {
- ResultBean<String> resultBean = new ResultBean<>();
- resultBean.setCode(ResultCode.OK);
- resultBean.setResultData("请求成功");
- return resultBean;
- }
- @PostMapping("/index/add")
- @ApiOperation(value = "add", notes = "新增")
- public ResultBean<String> add(Users users) {
- ResultBean<String> resultBean = new ResultBean<>();
- resultBean.setCode(ResultCode.OK);
- resultBean.setResultData("请求成功");
- return resultBean;
- }
- @DeleteMapping("/index/delete/{id}")
- @ApiOperation(value = "delete", notes = "删除")
- public ResultBean<String> delete(@PathVariable(value = "id") String id) {
- ResultBean<String> resultBean = new ResultBean<>();
- resultBean.setCode(ResultCode.OK);
- resultBean.setResultData("请求成功");
- return resultBean;
- }
- }
3-5 测试
主要是测试接口 api, 所以这里就没有数据库访问的业务逻辑层
启动项目, 访问 http://localhost:8080/swagger-ui.html#/
展开 add 接口
3-6 注意!!!!! 生成环境需要把 swagger 禁用, swagger 只是适合在开发和测试环境中使用, 源代码 https://github.com/lishun1005/swaggerapi
来源: https://www.cnblogs.com/lishun1005/p/8484844.html