Spring Boot 集成 Swagger-Bootstrap-UI,非常棒的解决方案
Java后端编程 文章源自JAVA秀-https://www.javaxiu.com/32978.html
之前在创业公司待的时候,用过swagger,因为我第一天来这家公司工作,第一个任务就是做接口文档自动化。文章源自JAVA秀-https://www.javaxiu.com/32978.html
后来觉得它不太好用,在浏览技术网站的时候,偶然发现swagger-bootstrap-ui,于是便重构了,把swagger-bootstrap-ui整合进来,后来发现不仅仅对我们后端有帮助,主要方便我们将接口进行归类,同样对安卓小伙伴也有帮助,他们可以看这个接口文档进行联调。文章源自JAVA秀-https://www.javaxiu.com/32978.html
当初我使用swagger-boostrap-ui的时候,那个时候还是1.x版本,如今swagger-bootsrap-ui到2.x,同时也更改名字knife4j,适用场景从过去的单体到微服务。也算是见证咱们国人自己的开源项目从小到大。文章源自JAVA秀-https://www.javaxiu.com/32978.html
文章源自JAVA秀-https://www.javaxiu.com/32978.html
一、添加Maven依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version></dependency><dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.6</version></dependency>
文章源自JAVA秀-https://www.javaxiu.com/32978.html二、添加配置类
@Configuration@EnableSwagger2@EnableSwaggerBootstrapUIpublic class SwaggerConfiguration { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.blog.tutorial.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("swagger-bootstrap-ui RESTful APIs") .description("swagger-bootstrap-ui") .termsOfServiceUrl("http://localhost:5050/") .contact("developer@mail.com") .version("1.0") .build(); }}
文章源自JAVA秀-https://www.javaxiu.com/32978.html三、启动项目文章源自JAVA秀-https://www.javaxiu.com/32978.html
启动项目,不报错,然后访问地址: http://ip:port/doc.html 即可, 效果图,如下:文章源自JAVA秀-https://www.javaxiu.com/32978.html
文章源自JAVA秀-https://www.javaxiu.com/32978.html
测试接口,效果图如下:文章源自JAVA秀-https://www.javaxiu.com/32978.html
文章源自JAVA秀-https://www.javaxiu.com/32978.html
调式相当于用 PostMan 测试接口。文章源自JAVA秀-https://www.javaxiu.com/32978.html
四、常用注解
和 swagger 一样,swagger 用的注解,swagger-bootstrap-ui 仍能用。 不过结合我的开发经验来看,最常用的也就两个,@Api 和 @ApiOperation。 @Api 的效果,如图:文章源自JAVA秀-https://www.javaxiu.com/32978.html
文章源自JAVA秀-https://www.javaxiu.com/32978.html
@ApiOperation 的效果,如图:文章源自JAVA秀-https://www.javaxiu.com/32978.html
文章源自JAVA秀-https://www.javaxiu.com/32978.html
由此,我们很容易就看出来,它们的含义是什么,一个是接口分类说明,一个是接口方法说明。文章源自JAVA秀-https://www.javaxiu.com/32978.html
至于这里不用 swagger 的参数注解,主要原因是不想加太多的注解从而增加代码的数量,造成太多冗余。文章源自JAVA秀-https://www.javaxiu.com/32978.html
例子中的Controller代码:文章源自JAVA秀-https://www.javaxiu.com/32978.html
@RestController@RequestMapping("/user")@Api(tags = {"用户管理"}, description = "用户管理")public class UserController { @Autowired private UsersService usersService; @GetMapping("/list") @ApiOperation(value = "用户列表") public List<Users> list() { return usersService.list(); }}
文章源自JAVA秀-https://www.javaxiu.com/32978.html五、其它补充文章源自JAVA秀-https://www.javaxiu.com/32978.html
https://www.cnblogs.com/youcong/p/9196157.html文章源自JAVA秀-https://www.javaxiu.com/32978.html
https://www.cnblogs.com/youcong/p/9196157.html文章源自JAVA秀-https://www.javaxiu.com/32978.html
六、可能遇到的问题
1.访问不到接口文档界面白版
一般是被拦截了 (shiro或springsecurity机制) 或者是配置错误。文章源自JAVA秀-https://www.javaxiu.com/32978.html
2.访问接口文档界面出来了,但扫描不到接口
主要是配置类的缘故,配置类有个包扫描,必须配置为controller路径。如图所示:文章源自JAVA秀-https://www.javaxiu.com/32978.html
文章源自JAVA秀-https://www.javaxiu.com/32978.html
如果还有其它问题,可以去官方文档上找,官方文档有一个常规问题列表和解决方案,如图所示:文章源自JAVA秀-https://www.javaxiu.com/32978.html
文章源自JAVA秀-https://www.javaxiu.com/32978.html
如果问题非常奇葩的话,实在解决不了 (在参考官方文档说明和搜索的前提下,仍解决不了,把问题详细描述和关键性代码提到该开源项目的 issue 上,原文地址:mrw.so/5GHvNy)。文章源自JAVA秀-https://www.javaxiu.com/32978.html
项目获取方式文章源自JAVA秀-https://www.javaxiu.com/32978.html
点击下方公众号,回复:605文章源自JAVA秀-https://www.javaxiu.com/32978.html
文章源自JAVA秀-https://www.javaxiu.com/32978.html

评论