## Swagger UI 简单使用 > [Springfox](http://springfox.github.io/springfox/ "Springfox") : SpringBoot下[swagger](https://swagger.io/ "swagger") UI的简单的介绍以及使用 ### 介绍 在SpringBoot下使用Swagger可以快速生成API相关信息并页面展示,便于API测试及生成API文档,下面是一段Swagger的介绍: > swagger是一个流行的API开发框架,框架以“开放API声明”(OpenAPI Specification,OAS)为基础,对整个API的开发周期都提供了相应的解决方案。OAS本身是一个API规范,用于描述一整套API接口信息,在设计的时候通常是YAML格式,这种格式书写起来比较方便,而在网络中传输时又会以json形式居多。 > swagger-springmvc是一个基于Spring的组件,用于将swagger集成到springmvc中来。而springfox则是从这个组件发展而来,springfox-swagger2这个组件帮助我们自动生成OSA描述json文件,另外一个组件springfox-swagger-ui就是将这个json文件解析出来,用一种更友好的方式呈现出来。 ### 引入依赖 基于gradle创建一个简单的sprinboot项目,并以此说明下springfox的简单使用。 ```groovy //springfox使用2.9.2版本 compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2' compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2' ``` ### Swagger2初始化配置 SwaggerConfig.java类来初始化一些Swagger相关配置:主要是需要提供一个Docket实例,该实例用来配置Swagger2需要扫描API的包,请求路径,以及其他API描述信息 ```java @Configuration @EnableSwagger2 //启用EnableSwagger2自动化配置 public class SwaggerConfig implements WebMvcConfigurer { @Bean public Docket customDocket() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("swagger.demo.controller")) .paths(PathSelectors.any())//过滤的路径 .build(); } private ApiInfo apiInfo() { Contact contact = new Contact("yebukong", "https://yebukong.com/", "yebukong@qq.com"); return new ApiInfoBuilder() .title("swagger-demo API接口") .description("简单的swagger UI用法展示") .contact(contact) .version("0.0.1") .build(); } /** * 添加Swagger2静态文件映射 **/ @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); } } ``` ### API上加入Swagger相关注解 除了上述的SwaggerConfig类配置外,还需要在Controller上加入Swagger相关注解,以提供更详细的API信息,关于注解更详细的用法,可以参考[swagger常用注解说明](https://www.jianshu.com/p/12f4394462d5 "swagger常用注解说明") ```java /** * UserController * * @author Mine * @date 2019/04/10 00:04:21 */ //@Api用在类上,说明该类的作用 //参数详细说明 https://www.jianshu.com/p/12f4394462d5 @Api(tags = { "用户api组" }, protocols = "http", hidden = false) @Controller() @RequestMapping("/u") public class UserController { @ApiOperation(tags = { "公共api组" }, notes = "获取指定用户,通过URL传值", value = "获取指定用户") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "path") }) @ApiResponses({ @ApiResponse(code = 400, message = "请求参数没填好"), @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对") }) @RequestMapping(value = "/{id}", method = RequestMethod.GET) @ResponseBody public R<UserInfo> get(@PathVariable("id") String id) throws Exception { UserInfo ui = new UserInfo(); ui.setId(id); ui.setName("Test"); ui.setPassword("code"); ui.setStatus("Vaild"); return R.ok(ui); } @ApiOperation(notes = "更新指定用户", value = "更新指定用户") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "path") }) @RequestMapping(value = "/{id}", method = RequestMethod.POST) @ResponseBody public R<Object> update(@RequestBody() UserInfo userinfo) throws Exception { System.out.println(userinfo); return R.ok(null); } } ``` ### 验证 在项目启动后访问以下路径验证: API信息:http://localhost:8080/v2/api-docs API信息展示页:http://localhost:8080/swagger-ui.html 效果图:  ### 相关代码地址 Gitee: https://gitee.com/yebukong/swagger-demo GitHub: https://github.com/yebukong/swagger-demo ### 参考链接 > https://www.cnblogs.com/getupmorning/p/7267076.html > https://www.jianshu.com/p/12f4394462d5 :stuck_out_tongue: ------------ > 本文由 [叶不空](https://yebukong.com "叶不空") 创作,采用 [知识共享署名 4.0 国际许可协议](https://creativecommons.org/licenses/by/4.0/ "知识共享署名 4.0 国际许可协议")进行许可,转载请附上链接! > 本文链接: [https://yebukong.com/article/1107706214319489025.html](https://yebukong.com/article/1107706214319489025.html "Swagger UI 简单使用")