Swagger介绍-一套流行的API框架

转载 2017年01月03日 10:42:24

简介

 

号称:世界最流行的API框架

官网:http://swagger.io/

解决什么问题:在前后台分离的开发模式中,减小接口定义沟通成本,方便开发过程中测试,自动生成接口文档。

实例代码位置:https://github.com/pumadong/cl-roadshow/tree/master/roadshow-swagger

 

swagger使用方式

 

第一种

定义YAML文件,然后可以生成各种语言的代码框架,对于后台程序员来说,较少人会愿意写出一堆YAML格式。

第二种

swagger有各种语言的插件,可以通过配置及少量代码,生成接口文档及测试界面。

我们多做了:一次性的配置及少量注解代码。

我们不用再做:1、到Wiki中更新接口文档;2、Postman形式的测试;3、Curl形式的测试

 

swagger java使用介绍

 

对于一个SpringMVC项目,使用swagger的配置如下:

pom.xml

 

  1. <!-- Swagger -->  
  2. <dependency>  
  3.     <groupId>io.swagger</groupId>  
  4.     <artifactId>swagger-core</artifactId>  
  5.     <version>1.5.8</version>  
  6. </dependency>  
  7. <dependency>  
  8.     <groupId>io.springfox</groupId>  
  9.     <artifactId>springfox-swagger2</artifactId>  
  10.     <version>2.4.0</version>  
  11. </dependency>  
  12. <dependency>  
  13.     <groupId>io.springfox</groupId>  
  14.     <artifactId>springfox-swagger-ui</artifactId>  
  15.     <version>2.4.0</version>  
  16. </dependency>  

 

SwaggerConfiguration.java

 

  1. @Configuration  
  2. @EnableSwagger2  
  3. public class SwaggerConfiguration {  
  4.     @Bean  
  5.     public Docket api() {  
  6.         return new Docket(DocumentationType.SWAGGER_2)  
  7.                 .select()  
  8.                 .apis(RequestHandlerSelectors.any())  
  9.                 .paths(PathSelectors.any())  
  10.                 .build();  
  11.     }  
  12. }  

 

SwaggerWebMvcConfigurerAdapter.java

 

  1. @Configuration  
  2. @EnableWebMvc  
  3. @ComponentScan(basePackages = "com.xx.travel.csc.stat.controller")  
  4. public class SwaggerWebMvcConfigurerAdapter extends WebMvcConfigurerAdapter {  
  5.    
  6.     @Bean  
  7.     public ViewResolver viewResolver() {  
  8.         InternalResourceViewResolver viewResolver = new InternalResourceViewResolver();  
  9.         viewResolver.setViewClass(JstlView.class);  
  10.         viewResolver.setPrefix("/WEB-INF/views/");  
  11.         viewResolver.setSuffix(".jsp");  
  12.         return viewResolver;  
  13.     }  
  14.    
  15.     @Bean  
  16.     public MessageSource messageSource() {  
  17.         ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();  
  18.         messageSource.setBasename("messages");  
  19.         return messageSource;  
  20.     }  
  21.     @Override  
  22.     public void addResourceHandlers(ResourceHandlerRegistry registry) {  
  23.         super.addResourceHandlers(registry);  
  24.         registry.addResourceHandler("swagger-ui.html")  
  25.                 .addResourceLocations("classpath:/META-INF/resources/");  
  26.         registry.addResourceHandler("/webjars/**")  
  27.                 .addResourceLocations("classpath:/META-INF/resources/webjars/");  
  28.     }  
  29.     @Override  
  30.     public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {  
  31.         configurer.enable();  
  32.     }  
  33. }  

 

 

Controller实例

然后,只要在我们的Controller里面增加注解 ApiOperation和ApiParam 即可。

 

  1. @Controller  
  2. @RequestMapping(value = "/stat")  
  3. public class SwaggerController {  
  4.        
  5.     @ResponseBody  
  6.     @RequestMapping(value = "/helloworld", method = RequestMethod.GET)  
  7.     @ApiOperation(nickname = "swagger-helloworld", value = "Swagger的世界", notes = "测试HelloWorld")  
  8.     public String helloWorld(@ApiParam(value = "昵称") @RequestParam String nickname) {  
  9.         return "Hello world, " + nickname;  
  10.     }  
  11.        
  12.     @ResponseBody  
  13.     @RequestMapping(value = "/objectio", method = RequestMethod.POST)  
  14.     @ApiOperation(nickname = "swagger-objectio", value = "Swagger的ObjectIO", notes = "测试对象输入输出")  
  15.     public SwaggerOutput objectIo(@ApiParam(value = "输入") @RequestBody SwaggerInput input) {  
  16.         SwaggerOutput output = new SwaggerOutput();  
  17.         output.setId(input.getId());  
  18.         output.setName("Swagger");  
  19.         return output;  
  20.     }  
  21. }  

 

Web界面

启动项目,输入Http://Path/swagger-ui.html,就可以给前端展示相关的API文档,并像使用Postman以及Curl命令一样,通过Web界面进行接口测试。

 

 http://blog.csdn.net/puma_dong/article/details/51752099

Spring MVC全局异常后返回JSON异常数据

Spring MVC全局异常后返回JSON异常数据 问题:         当前项目是作为手机APP后台支持,使用spring mvc + mybaits + shiro进行开发。后台服务与手机端交互...

springmvc简单实现权限控制

用过了Spring Security,一般都不会采用这种简单的自定义方式.自定义当然灵活自由,越要完善,也就意味做的工作越多.使用框架,别人考虑得相对周到,比如spring security的防止攻击...
  • xiejx618
  • xiejx618
  • 2015年02月11日 11:50
  • 27209

在 Java2中,有一套设计优良的接口和类组成了Java集合框架Collection,使程序员操作成批的数据或对象元素极为方便。这些接口和类有很多对抽象数据类型操作的API,而这是我们常用的且在数据结

深入理解Java的接口和抽象类   对于面向对象编程来说,抽象是它的一大特征之一。在Java中,可以通过两种形式来体现OOP的抽象:接口和抽象类。这两者有太多相似的地方,又有太多不同的地方。很多...
  • john548
  • john548
  • 2016年08月17日 19:39
  • 276

swagger-ui-1.0.13框架

  • 2017年10月28日 12:50
  • 1.03MB
  • 下载

Swagger API接口创建

  • 2017年11月27日 16:42
  • 498KB
  • 下载

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

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

Swagger编写API文档的YAML示例

  • 2017年02月14日 14:53
  • 8KB
  • 下载

Swagger生成API文档

一、swagger介绍 使用springMVC集成swagger-ui生成 Restful风格的API文档,可以省略手动编写接口文档的过程,也解决了接口变化需要维护接口文档的过程。 swagger-u...
  • sreng
  • sreng
  • 2016年12月23日 15:55
  • 643

Spring Boot Swagger2 构建RESTful API

  • 2016年12月30日 15:31
  • 41KB
  • 下载
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:Swagger介绍-一套流行的API框架
举报原因:
原因补充:

(最多只允许输入30个字)