使用Swagger2构建SpringMVC项目中的Restful API文档
使用Swagger自动生成API文档,不仅增加了项目的可维护性,还提高了API的透明度更利于快速测试等工作,便于更快地发现和解决问题。
本篇文章只记录整合过程,关于Security Configuration等其他特性这里就不展开讲了,感兴趣的可以通过以下链接了解更多。
参考文档:
- https://howtodoinjava.com/swagger2/swagger-spring-mvc-rest-example/
- http://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
- http://blog.didispace.com/springbootswagger2/
项目中各组件的版本情况:
- spring.version=4.3.18.RELEASE
- jackson.version=2.9.
- swagger.version=2.7.
核心的pom配置(spring的省略):
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger2</artifactId>
- <version>${swagger.version}</version>
- </dependency>
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger-ui</artifactId>
- <version>${swagger.version}</version>
- </dependency>
- <dependency>
- <groupId>com.fasterxml.jackson.core</groupId>
- <artifactId>jackson-databind</artifactId>
- <version>${jackson.version}</version>
- </dependency>
- <dependency>
- <groupId>com.fasterxml.jackson.core</groupId>
- <artifactId>jackson-core</artifactId>
- <version>${jackson.version}</version>
- </dependency>
- <dependency>
- <groupId>com.fasterxml.jackson.core</groupId>
- <artifactId>jackson-annotations</artifactId>
- <version>${jackson.version}</version>
- </dependency>
编写Swagger的配置类:
tip:做了拦截处理的同学需要注意开放swagger的资源访问路径:/swagger-resources/*、/swagger-ui.html、/v2/api-docs、/webjars/*
- @Configuration
- @EnableSwagger2
- @EnableWebMvc
- @ComponentScan("springfox")
- public class SwaggerConfig extends WebMvcConfigurerAdapter {
- @Bean
- public Docket createRestApi() {
- return new Docket(DocumentationType.SWAGGER_2)
- .select()
- .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
- .paths(PathSelectors.any())
- .build()
- .apiInfo(apiInfo());
- }
- private ApiInfo apiInfo() {
- return new ApiInfoBuilder()
- .title("REST API 描述文档")
- .description("REST API 描述文档")
- .version("1.0")
- .termsOfServiceUrl("http://localhost:9080/")
- .contact(new Contact("lichmama", "", ""))
- .license("Apache License 2.0")
- .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
- .build();
- }
- @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/");
- }
- }
在springmvc-servlet.xml中增加配置:
- <bean class="com.lichmama.demo.core.swagger.SwaggerConfig" />
在RestController上使用Swagger的注解(其中ApiOperation和ApiImplicitParam尤为关键),用以自动生成文档:
- @RestController
- @RequestMapping("/config")
- @Api(description = "配置管理接口")
- @Slf4j
- public class ConfigAction {
- @PostMapping("/set")
- @ApiOperation(value = "更改或新增配置信息")
- @ApiResponses(value = { @ApiResponse(code = 500, message = "系统错误"), @ApiResponse(code = 0, message = "成功") })
- @ApiImplicitParams({ @ApiImplicitParam(name = "key", value = "键", paramType = "form", dataType = "string"),
- @ApiImplicitParam(name = "value", value = "值", paramType = "form", dataType = "string") })
- public ActionMessage setConfig(String key, String value) {
- log.debug("key: {}, value: {}", key, value);
- ConfigUtil.setConfig(key, value);
- return ActionStatus.success();
- }
- @GetMapping("/get")
- @ApiOperation(value = "获取配置信息")
- @ApiImplicitParam(name = "key", value = "键", paramType = "query", dataType = "string")
- public Map<String, Object> getConfig(String key) {
- Object value = ConfigUtil.getConfig(key);
- log.debug("key: {}, value: {}", key, value);
- Map<String, Object> map = new HashMap<>();
- map.put(key, value);
- return map;
- }
- }
启动项目,访问http://{host:port}/{project}/swagger-ui.html查看配置是否生效:
看上去没有问题,测试下:
ps:网上关于swagger的文章配置上多数都有些问题,所以不能直接照搬使用。自己部署swagger时要根据实际项目来修改配置,比如spring、swagger的版本等。
使用Swagger2构建SpringMVC项目中的Restful API文档的更多相关文章
- JavaWeb项目中集成Swagger API文档
1.增加依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-sw ...
- Spring Boot 中使用 Swagger2 构建强大的 RESTful API 文档
项目现状:由于前后端分离,没有很好的前后端合作工具. 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型.HTTP头部信息.HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下 ...
- Spring Boot中使用Swagger2构建强大的RESTful API文档
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
- Spring Boot中使用Swagger2构建RESTful API文档
在开发rest api的时候,为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题: 1.由于接口众多,并且细 ...
- Spring Boot 入门系列(二十二)使用Swagger2构建 RESTful API文档
前面介绍了如何Spring Boot 快速打造Restful API 接口,也介绍了如何优雅的实现 Api 版本控制,不清楚的可以看我之前的文章:https://www.cnblogs.com/zha ...
- 使用Swagger2构建强大的RESTful API文档(1)(二十二)
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
- springboot集成swagger2构建RESTful API文档
在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可 ...
- SpringBoot_06_使用Swagger2构建强大的RESTful API文档
二.参考资料 1.Spring Boot中使用Swagger2构建强大的RESTful API文档 2.
- Spring Boot教程(二十二)使用Swagger2构建强大的RESTful API文档(1)
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
随机推荐
- Markdown
Cygwin Markdown是一种可以使用普通文本编辑器编写的标记语言,通过简单的标记语法,它可以使普通文本内容具有一定的格式. Markdown具有一系列衍生版本,用于扩展Markdown ...
- STM (软件事务内存)
- Jquery实现左右轮播效果
首先展示下静态布局h5代码,代码非常简单. <div id="slide"> <ul class="pic-list"> <li& ...
- Python 字符串多替换时性能基准测试
结论 先说结果, 直接替换是最好的. replace 一层层用, 方法笨了一点, 还可以. 时间消耗: tx2 < tx3 < tx1 < tx4 t2 < t3 < t ...
- JS基石之-----防抖节流函数
防抖和节流函数 阅读目录 一 .防抖函数 二 .节流函数 三 .个人理解两者的区别 一.防抖函数 1.1 概念: 触发高频事件后n秒内函数只会执行一次,如果n秒内高频事件再次被触发,则重新计算 ...
- JavaScript之二十三种设计模式
23种JavaScript设计模式 原文链接:https://boostlog.io/@sonuton/23-javascript-design-patterns-5adb006847018500 ...
- iOS批量添加SDK自动打包GUI工具
背景 1.之前在给游戏开发商做SDK接入技术支持的时候,很多cp对iOS开发技术并不是很了解,对接SDK和打包都很迷糊,虽然我们根据他们的开发环境输出了不同的插件解决方案,这一步已经把接入SDK的复杂 ...
- github操作
Github使用 1. 注册 官网:https://github.com/ 搜索项目 以压缩包的的形式下载demo 克隆项目 创建仓库 克隆项目,编写,完成上传,使用https请求,需要输入用户名 ...
- Apache源码编译安装脚本
Apache是开源的的.最流行的Web服务器软件之一,它快速.可靠并且可通过简单的API扩充,将Perl/Python/PHP等解释器编译到服务器中.Apache的模块超多,以及具有运行稳定,强大 ...
- Python 的版本控制
版本控制工具的差异 这里介绍几个工具:pyenv.pyvenv. venv.virtualenv.pyenv-virtualenv virtualenv 是针对python的包的多版本管理,通过将py ...