springboot 接口文档_11. Springboot整合Swagger接口文档

引言：

前后端分离开发时，前后端对接接口时，必不可少的就是接口文档了，后端所写的所有接口和参数都在文档中体现，前端按照文档对接就行。但在实际开发中，我们的接口总是会有改变，这个时候也要不停地修改文档，还好有一些工具可以来帮助我们维护修改文档，swagger就是我们接下来要讲的工具。

什么是Swagger？

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger 的优势

• 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。

• 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

SpringBoot整合Swagger：

1. 在pom.xml文件中添加第三方swagger依赖

io.springfoxspringfox-swagger22.9.2io.springfoxspringfox-swagger-ui2.9.2

2.配置Swagger 配置类

    @Configuration
@EnableSwagger2
@Profile("dev")public class SwaggerConfigure {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()//此处为我们要扫描的项目包路径，自行修改.apis(RequestHandlerSelectors.basePackage("com.example.mechanics.web"))
                .paths(PathSelectors.any())
                .build();}private ApiInfo apiInfo() {return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("Spring Boot相关文章")
                .termsOfServiceUrl("")
                .contact("程序猿木大大")
                .version("1.0")
                .build();}
}

3. 写个小demo测试下

/** *  *  前端控制器 *  * * @author 程序猿木大大 * @since 2020-09-21 */@Controller@RequestMapping("/user")@Api(tags="用户模块")public class UserController {    /**     * swagger接口api注解：     * @Api 描述类/接口的主要用途     * @ApiOperation 描述方法用途     * @ApiImplicitParam 描述方法的参数     * @ApiImplicitParams 描述方法的参数(Multi-Params)     * @ApiIgnore 忽略某类/方法/参数的文档     *     */    @RequestMapping("hello")@ResponseBody    @ApiOperation(value="根据用户名获取用户信息",notes="根据输入的用户名查询该用户的信息")@ApiImplicitParam(name="uname",value="用户名",required=true,dataType="String")public String hello(){return "hello";    }
}

4. 重中之重：

在启动类上添加@EnableSwagger2注解

@SpringBootApplication@EnableSwagger2public class MachineryApplication {public static void main(String[] args) {
        SpringApplication.run(MachineryApplication.class, args);    }
}

5. 访问接口文档：

接口查看地址可以通过服务地址 /swagger-ui.html 来访问，见图 。

此时就可以看到我在controller上写的用户模块在上面已经显示出来。点开用户模块：

这样就能看到我们写的接口详情了。

end

往期推荐

springboot解决跨域问题(Cors)

2. Springboot中详细配置SSL证书

3. Springboot整合MyBatis-Plus

4. Springboot配置日志管理系统

5. SpringBoot+Redis分布式锁

6. Springboot整合Shiro权限管理

7. Springboot自动配置的原理

关注我们

不点关注，我们哪来故事？

你点的每一个在看，我都认真当成了喜欢