使用Swagger自动生成API文档,不仅增加了项目的可维护性,还提高了API的透明度更利于快速测试等工作,便于更快地发现和解决问题。

本篇文章只记录整合过程,关于Security Configuration等其他特性这里就不展开讲了,感兴趣的可以通过以下链接了解更多。

参考文档:

  1. https://howtodoinjava.com/swagger2/swagger-spring-mvc-rest-example/
  2. http://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
  3. http://blog.didispace.com/springbootswagger2/

项目中各组件的版本情况:

  1. spring.version=4.3.18.RELEASE
  2. jackson.version=2.9.
  3. swagger.version=2.7.

核心的pom配置(spring的省略):

  1. <dependency>
  2. <groupId>io.springfox</groupId>
  3. <artifactId>springfox-swagger2</artifactId>
  4. <version>${swagger.version}</version>
  5. </dependency>
  6.  
  7. <dependency>
  8. <groupId>io.springfox</groupId>
  9. <artifactId>springfox-swagger-ui</artifactId>
  10. <version>${swagger.version}</version>
  11. </dependency>
  12.  
  13. <dependency>
  14. <groupId>com.fasterxml.jackson.core</groupId>
  15. <artifactId>jackson-databind</artifactId>
  16. <version>${jackson.version}</version>
  17. </dependency>
  18. <dependency>
  19. <groupId>com.fasterxml.jackson.core</groupId>
  20. <artifactId>jackson-core</artifactId>
  21. <version>${jackson.version}</version>
  22. </dependency>
  23. <dependency>
  24. <groupId>com.fasterxml.jackson.core</groupId>
  25. <artifactId>jackson-annotations</artifactId>
  26. <version>${jackson.version}</version>
  27. </dependency>

编写Swagger的配置类:

tip:做了拦截处理的同学需要注意开放swagger的资源访问路径:/swagger-resources/*、/swagger-ui.html、/v2/api-docs、/webjars/*

  1. @Configuration
  2. @EnableSwagger2
  3. @EnableWebMvc
  4. @ComponentScan("springfox")
  5. public class SwaggerConfig extends WebMvcConfigurerAdapter {
  6.  
  7. @Bean
  8. public Docket createRestApi() {
  9. return new Docket(DocumentationType.SWAGGER_2)
  10. .select()
  11. .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
  12. .paths(PathSelectors.any())
  13. .build()
  14. .apiInfo(apiInfo());
  15. }
  16.  
  17. private ApiInfo apiInfo() {
  18. return new ApiInfoBuilder()
  19. .title("REST API 描述文档")
  20. .description("REST API 描述文档")
  21. .version("1.0")
  22. .termsOfServiceUrl("http://localhost:9080/")
  23. .contact(new Contact("lichmama", "", ""))
  24. .license("Apache License 2.0")
  25. .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
  26. .build();
  27. }
  28.  
  29. @Override
  30. public void addResourceHandlers(ResourceHandlerRegistry registry) {
  31. registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
  32. registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
  33. }
  34. }

在springmvc-servlet.xml中增加配置:

  1. <bean class="com.lichmama.demo.core.swagger.SwaggerConfig" />

在RestController上使用Swagger的注解(其中ApiOperation和ApiImplicitParam尤为关键),用以自动生成文档:

  1. @RestController
  2. @RequestMapping("/config")
  3. @Api(description = "配置管理接口")
  4. @Slf4j
  5. public class ConfigAction {
  6.  
  7. @PostMapping("/set")
  8. @ApiOperation(value = "更改或新增配置信息")
  9. @ApiResponses(value = { @ApiResponse(code = 500, message = "系统错误"), @ApiResponse(code = 0, message = "成功") })
  10. @ApiImplicitParams({ @ApiImplicitParam(name = "key", value = "键", paramType = "form", dataType = "string"),
  11. @ApiImplicitParam(name = "value", value = "值", paramType = "form", dataType = "string") })
  12. public ActionMessage setConfig(String key, String value) {
  13. log.debug("key: {}, value: {}", key, value);
  14. ConfigUtil.setConfig(key, value);
  15. return ActionStatus.success();
  16. }
  17.  
  18. @GetMapping("/get")
  19. @ApiOperation(value = "获取配置信息")
  20. @ApiImplicitParam(name = "key", value = "键", paramType = "query", dataType = "string")
  21. public Map<String, Object> getConfig(String key) {
  22. Object value = ConfigUtil.getConfig(key);
  23. log.debug("key: {}, value: {}", key, value);
  24. Map<String, Object> map = new HashMap<>();
  25. map.put(key, value);
  26. return map;
  27. }
  28. }

启动项目,访问http://{host:port}/{project}/swagger-ui.html查看配置是否生效:

看上去没有问题,测试下:

ps:网上关于swagger的文章配置上多数都有些问题,所以不能直接照搬使用。自己部署swagger时要根据实际项目来修改配置,比如spring、swagger的版本等。

使用Swagger2构建SpringMVC项目中的Restful API文档的更多相关文章

  1. JavaWeb项目中集成Swagger API文档

    1.增加依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-sw ...

  2. Spring Boot 中使用 Swagger2 构建强大的 RESTful API 文档

    项目现状:由于前后端分离,没有很好的前后端合作工具. 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型.HTTP头部信息.HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下 ...

  3. Spring Boot中使用Swagger2构建强大的RESTful API文档

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

  4. Spring Boot中使用Swagger2构建RESTful API文档

    在开发rest api的时候,为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题: 1.由于接口众多,并且细 ...

  5. Spring Boot 入门系列(二十二)使用Swagger2构建 RESTful API文档

    前面介绍了如何Spring Boot 快速打造Restful API 接口,也介绍了如何优雅的实现 Api 版本控制,不清楚的可以看我之前的文章:https://www.cnblogs.com/zha ...

  6. 使用Swagger2构建强大的RESTful API文档(1)(二十二)

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

  7. springboot集成swagger2构建RESTful API文档

    在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可 ...

  8. SpringBoot_06_使用Swagger2构建强大的RESTful API文档

    二.参考资料 1.Spring Boot中使用Swagger2构建强大的RESTful API文档 2.

  9. Spring Boot教程(二十二)使用Swagger2构建强大的RESTful API文档(1)

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

随机推荐

  1. ​ Markdown

    Cygwin ​ Markdown是一种可以使用普通文本编辑器编写的标记语言,通过简单的标记语法,它可以使普通文本内容具有一定的格式. ​ Markdown具有一系列衍生版本,用于扩展Markdown ...

  2. STM (软件事务内存)

  3. Jquery实现左右轮播效果

    首先展示下静态布局h5代码,代码非常简单. <div id="slide"> <ul class="pic-list"> <li& ...

  4. Python 字符串多替换时性能基准测试

    结论 先说结果, 直接替换是最好的. replace 一层层用, 方法笨了一点, 还可以. 时间消耗: tx2 < tx3 < tx1 < tx4 t2 < t3 < t ...

  5. JS基石之-----防抖节流函数

    防抖和节流函数   阅读目录 一 .防抖函数 二 .节流函数 三 .个人理解两者的区别   一.防抖函数 1.1 概念: 触发高频事件后n秒内函数只会执行一次,如果n秒内高频事件再次被触发,则重新计算 ...

  6. JavaScript之二十三种设计模式

    23种JavaScript设计模式   原文链接:https://boostlog.io/@sonuton/23-javascript-design-patterns-5adb006847018500 ...

  7. iOS批量添加SDK自动打包GUI工具

    背景 1.之前在给游戏开发商做SDK接入技术支持的时候,很多cp对iOS开发技术并不是很了解,对接SDK和打包都很迷糊,虽然我们根据他们的开发环境输出了不同的插件解决方案,这一步已经把接入SDK的复杂 ...

  8. github操作

    Github使用 1. 注册 ​ 官网:https://github.com/ 搜索项目 以压缩包的的形式下载demo 克隆项目 创建仓库 克隆项目,编写,完成上传,使用https请求,需要输入用户名 ...

  9. Apache源码编译安装脚本

      Apache是开源的的.最流行的Web服务器软件之一,它快速.可靠并且可通过简单的API扩充,将Perl/Python/PHP等解释器编译到服务器中.Apache的模块超多,以及具有运行稳定,强大 ...

  10. Python 的版本控制

    版本控制工具的差异 这里介绍几个工具:pyenv.pyvenv. venv.virtualenv.pyenv-virtualenv virtualenv 是针对python的包的多版本管理,通过将py ...