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

<repositories>  

    <repository>  

      <id>jcenter-release</id>  

      <name>jcenter</name>  

      <url>http://oss.jfrog.org/artifactory/oss-release-local/</url>  

    </repository>  

</repositories>  

  

<dependency>  

    <groupId>com.mangofactory</groupId>  

    <artifactId>swagger-springmvc</artifactId>  

    <version>1.0.1</version>  

</dependency>  

后台配置：

途径一：

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

[html] view
plain copy

<mvc:annotation-driven/>  

   <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />  

   <!-- 对包中的所有类进行扫描，以完成Bean创建和自动依赖注入的功能 稍后会创建该包：webmvct.cmd -->      

<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

@Configuration  

@EnableSwagger //Loads the spring beans required by the framework  

@ComponentScan("com.test")  

public class MySwaggerConfig {  

    private SpringSwaggerConfig springSwaggerConfig;  

  

       /**  

        * Required to autowire SpringSwaggerConfig  

        */  

       @Autowired  

       public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {  

          this.springSwaggerConfig = springSwaggerConfig;  

       }  

  

       /**  

        * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc framework - allowing for multiple  

        * swagger groups i.e. same code base multiple swagger resource listings.  

        */  

       @Bean  

       public SwaggerSpringMvcPlugin customImplementation(){  

          return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)  

          .includePatterns(".*store.*");  

            

       }  

  

}  

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

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

controller类的样例：

[html] view
plain copy

@Api(value="/store",description="商店")  

@Controller  

@RequestMapping("/store")  

public class StoreController {  

      

      

    @RequestMapping(value = "/{storeid}",method=RequestMethod.GET)  

    @ResponseBody  

    @ApiOperation(value="获取商店信息",notes="通过商店id获取商店信息")  

    public Store getStore(String storeid){  

        return new Store();  

    }  

      

    @ApiOperation(value="获取商店信息",notes="通过商店name获取商店信息")  

    @ResponseBody  

    @RequestMapping(value = "/{storename}",method=RequestMethod.POST)  

    public Store getStore2(String storeid){  

        return new Store();  

    }  

}  

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

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

最终效果图：



以上配置参考：

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

swagger注解说明     点击打开链接



顶0
踩0
 
 

上一篇eclipse中打开含有汉字的properties文件显示乱码

下一篇svn
cleanup 失败解决方法

参考知识库

Java
Web知识库

9784关注|1042收录

Java
EE知识库

1230关注|581收录

Java
SE知识库

9485关注|454收录

猜你在找

JavaWeb基础核心技术
Java之路
国内第1套_Spring4 视频教程
JavaWeb程序设计
微信公众平台深度开发(Java版)

Spring MVC 教程快速入门深入分析
spring mvc 官方 教程 打war包 good
Spring MVC 教程快速入门深入分析
Spring MVC 教程快速入门深入分析
Spring MVC 教程快速入门深入分析

<iframe 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;"></iframe>

查看评论

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是什么原因，你遇到过吗？