前文:
在日常工作中,开发人员经常会遇到写接口文档的工作,一般都是word文档,带来书写麻烦、维护麻烦的问题,比如改了源代码忘了更新文档、解释不明确带来歧义、无法在线尝试等等。swagger就是为了解决这些问题而产生的。这是官方的例子,截图如下
![](https://img-blog.csdn.net/20150804214256804?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center)
swagger原理
后台:后端部分与Java集成,后最终会产生一个json文件。
前台:前台部分就是html、css、js文件,js利用后台产生的json文件构造api;
前台配置:
去 https://github.com/swagger-api/swagger-ui 下载zip包,解压后,将dist文件夹下的所有内容copy到,Java Web project的webapp下,比如,
![](https://img-blog.csdn.net/20150804214931505?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center)
maven依赖:
- <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文件中,添加配置
- <mvc:annotation-driven/>
- <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
-
- <context:component-scan base-package="webmvct.cmd"/>
解释:swagger会扫描 base-package包下的所有类,生成api文档
将docapi文件下的index.html文件,url改为本工程的路径,如下图,
![](https://img-blog.csdn.net/20150804215437810?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center)
截止到现在,最简单的swagger配置已经完成。访问 http://localhost:8080/hi/docapi/index.html 就可以看到效果。
途径二:如果想进一步的定制,比如只扫描某个包下的某些路径,那么就需要用到定制类,途径二是基于途径一在功能上的扩展,所以要想达到定制效果首先将途径一配置好。
创建swaggerspringconfig定制类,比如
- @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类的样例:
- @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是详细的说明方法作用
最终效果图:
![](https://img-blog.csdn.net/20150804223013230?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center)
以上配置参考:
swagger整合spring mvc的doc 点击打开链接
swagger注解说明 点击打开链接
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是什么原因,你遇到过吗?