swagger整合spring mvc教程

前文:

         在日常工作中,开发人员经常会遇到写接口文档的工作,一般都是word文档,带来书写麻烦、维护麻烦的问题,比如改了源代码忘了更新文档、解释不明确带来歧义、无法在线尝试等等。swagger就是为了解决这些问题而产生的。这是官方的例子,截图如下



swagger原理

后台:后端部分与Java集成,后最终会产生一个json文件。

前台:前台部分就是html、css、js文件,js利用后台产生的json文件构造api;



前台配置:

去 https://github.com/swagger-api/swagger-ui 下载zip包,解压后,将dist文件夹下的所有内容copy到,Java Web project的webapp下,比如,




maven依赖:

[html]  view plain  copy
  1. <repositories>  
  2.     <repository>  
  3.       <id>jcenter-release</id>  
  4.       <name>jcenter</name>  
  5.       <url>http://oss.jfrog.org/artifactory/oss-release-local/</url>  
  6.     </repository>  
  7. </repositories>  
  8.   
  9. <dependency>  
  10.     <groupId>com.mangofactory</groupId>  
  11.     <artifactId>swagger-springmvc</artifactId>  
  12.     <version>1.0.1</version>  
  13. </dependency>  

后台配置:

途径一:

spring的applicationcontext.xml文件中,添加配置

[html]  view plain  copy
  1. <mvc:annotation-driven/>  
  2.    <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />  
  3.    <!-- 对包中的所有类进行扫描,以完成Bean创建和自动依赖注入的功能 稍后会创建该包:webmvct.cmd -->      
  4. <context:component-scan base-package="webmvct.cmd"/>  

解释:swagger会扫描 base-package包下的所有类,生成api文档


将docapi文件下的index.html文件,url改为本工程的路径,如下图,


截止到现在,最简单的swagger配置已经完成。访问  http://localhost:8080/hi/docapi/index.html 就可以看到效果。


途径二:如果想进一步的定制,比如只扫描某个包下的某些路径,那么就需要用到定制类,途径二是基于途径一在功能上的扩展,所以要想达到定制效果首先将途径一配置好。

创建swaggerspringconfig定制类,比如

[html]  view plain  copy
  1. @Configuration  
  2. @EnableSwagger //Loads the spring beans required by the framework  
  3. @ComponentScan("com.test")  
  4. public class MySwaggerConfig {  
  5.     private SpringSwaggerConfig springSwaggerConfig;  
  6.   
  7.        /**  
  8.         * Required to autowire SpringSwaggerConfig  
  9.         */  
  10.        @Autowired  
  11.        public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {  
  12.           this.springSwaggerConfig = springSwaggerConfig;  
  13.        }  
  14.   
  15.        /**  
  16.         * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc framework - allowing for multiple  
  17.         * swagger groups i.e. same code base multiple swagger resource listings.  
  18.         */  
  19.        @Bean  
  20.        public SwaggerSpringMvcPlugin customImplementation(){  
  21.           return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)  
  22.           .includePatterns(".*store.*");  
  23.             
  24.        }  
  25.   
  26. }  


@componentscan,将com.test包下的类也包含在内进行扫描;

customImplementation方法的includePatterns可以进行过滤,只include含有store的路径


controller类的样例:

[html]  view plain  copy
  1. @Api(value="/store",description="商店")  
  2. @Controller  
  3. @RequestMapping("/store")  
  4. public class StoreController {  
  5.       
  6.       
  7.     @RequestMapping(value = "/{storeid}",method=RequestMethod.GET)  
  8.     @ResponseBody  
  9.     @ApiOperation(value="获取商店信息",notes="通过商店id获取商店信息")  
  10.     public Store getStore(String storeid){  
  11.         return new Store();  
  12.     }  
  13.       
  14.     @ApiOperation(value="获取商店信息",notes="通过商店name获取商店信息")  
  15.     @ResponseBody  
  16.     @RequestMapping(value = "/{storename}",method=RequestMethod.POST)  
  17.     public Store getStore2(String storeid){  
  18.         return new Store();  
  19.     }  
  20. }  

@api,用在类上,用于解释整个类。

@apioperation,用于方法上,value是笼统的介绍方法作用,notes是详细的说明方法作用


最终效果图:


以上配置参考:

swagger整合spring mvc的doc 点击打开链接

swagger注解说明     点击打开链接




0
0
 
 

参考知识库

img
Java Web知识库

img
Java EE知识库

img
Java SE知识库

猜你在找
JavaWeb基础核心技术
Java之路
国内第1套_Spring4 视频教程
JavaWeb程序设计
微信公众平台深度开发(Java版)
Spring MVC 教程快速入门深入分析
spring mvc 官方 教程 打war包 good
Spring MVC 教程快速入门深入分析
Spring MVC 教程快速入门深入分析
Spring MVC 教程快速入门深入分析
id="iframeu1607657_0" src="http://pos.baidu.com/ucym?sz=728x90&rdid=1607657&dc=2&di=u1607657&dri=0&dis=0&dai=2&ps=5650x563&coa=at%3D3%26rsi0%3D728%26rsi1%3D90%26pat%3D6%26tn%3DbaiduCustNativeAD%26rss1%3D%2523FFFFFF%26conBW%3D1%26adp%3D1%26ptt%3D0%26titFF%3D%2525E5%2525BE%2525AE%2525E8%2525BD%2525AF%2525E9%25259B%252585%2525E9%2525BB%252591%26titFS%3D%26rss2%3D%2523000000%26titSU%3D0%26ptbg%3D90%26piw%3D0%26pih%3D0%26ptp%3D0&dcb=BAIDU_SSP_define&dtm=HTML_POST&dvi=0.0&dci=-1&dpt=none&tsr=0&tpr=1468804740630&ti=swagger%E6%95%B4%E5%90%88spring%20mvc%E6%95%99%E7%A8%8B%20-%20wangjun5159%E7%9A%84%E4%B8%93%E6%A0%8F%20-%20%E5%8D%9A%E5%AE%A2%E9%A2%91%E9%81%93%20-%20CSDN.NET&ari=2&dbv=2&drs=3&pcs=1903x971&pss=1903x7810&cfv=0&cpl=5&chi=1&cce=true&cec=UTF-8&tlm=1468804740&rw=971&ltu=http%3A%2F%2Fblog.csdn.net%2Fwangjun5159%2Farticle%2Fdetails%2F47283125&ltr=https%3A%2F%2Fwww.baidu.com%2Flink%3Furl%3DWUHjJ3QWp-jnCvmm8mNnzRw6_HLgdN44wbBeSoYtc8JjTHoJU1rUN_0b3GNN7TWvMsg-8lRdcWhADwsCA8KMGDrEMAZ4Y5bK1pFBah3riQG%26wd%3D%26eqid%3Dce4b383f001ba58d00000003578c2d37&ecd=1&psr=1920x1080&par=1920x1030&pis=-1x-1&ccd=24&cja=false&cmi=7&col=zh-CN&cdo=-1&tcn=1468804741&qn=6bcc3a99aa4e3fb0&tt=1468804740612.23.105.107" width="728" height="90" align="center,center" vspace="0" hspace="0" marginwidth="0" marginheight="0" scrolling="no" frameborder="0" allowtransparency="true" style="border-width: 0px; border-style: initial; vertical-align: bottom; margin: 0px;">
查看评论
8楼  qq_35399691 2016-06-24 10:06发表 [回复]
你好,我引入了swagger-annotations-1.5.9,swagger-models-1.5.9,swagger-springmvc-1.0.2三个包之后,启动项目报错 class path resource [com/mangofactory/swagger/models/configuration/SwaggerModelsConfiguration.class] cannot be opened because it does not exist。我看了下jar包,发现swagger-springmvc-1.0.2jar包下面没有com.mangofactory.swagger.models包以及它的子包。请问你遇到过这个问题吗?我是还缺少什么jar包吗?谢谢。
Re:  干净的句号 2016-06-24 10:30发表 [回复]
回复qq_35399691:你的这个问题是版本不一致的问题。
swagger-springmvc-1.0.2
swagger-annotations-1.5.9,
swagger-models-1.5.9

把swagger-springmvc的版本号升级一下或者把其他两个降级
7楼  i_Creator 2015-12-03 17:55发表 [回复]
请问,Can't read swagger JSON from http://localhost:8080/hi/api-docs
Re:  干净的句号 2015-12-04 09:01发表 [回复]
回复i_Creator: http://localhost:8080/hi/api-docs,这是json的地址。

“hi”是工程名,你的工程可能不是这个吧?
6楼  笨笨de想你 2015-11-16 14:14发表 [回复]
你好!请问,页面出现
Can't read from server. It may not have the appropriate access-control-origin settings.
怎没解决。
Re:  干净的句号 2015-11-17 15:13发表 [回复]
回复笨笨de想你:你看看index.html中的url配置是否正确。样例代码中是http://localhost:8080/hi/api-docs
Re:  干净的句号 2015-11-17 14:05发表 [回复]
回复笨笨de想你:这个错误是由于ajax跨域访问造成的。找到跨域访问的地方,改为同源就可以了。如果想深入研究,可以参考我的博客,http://blog.csdn.net/wangjun5159/article/details/49096445
5楼  小锅不是铁打呢 2015-09-22 16:08发表 [回复]
博主Store类是什么?自定义的?还是?
Re:  干净的句号 2015-09-24 09:08发表 [回复]
回复小锅不是铁打呢:自定义的,类似class Store{ String id; String name;}这种
4楼  qqq460363410 2015-08-18 16:01发表 [回复]
请问,我进行整合的时候出现 Could not autowire method是什么原因,你遇到过吗?
Re:  干净的句号 2015-08-19 08:37发表 [回复]
回复qqq460363410:autowire使用方法错误吧,你看看@autowired,注解在什么地方了。
3楼  qqq460363410 2015-08-18 16:01发表 [回复]
请问,我进行整合的时候出现 Could not autowire method是什么原因,你遇到过吗?
2楼  qqq460363410 2015-08-18 16:00发表 [回复] [引用] [举报]
请问,我进行整合的时候出现 Could not autowire method是什么原因,你遇到过吗?
  • 0
    点赞
  • 1
    收藏
    觉得还不错? 一键收藏
  • 6
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论 6
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值