Swagger API文档自动生成
作者: 清逸成风 |来源:原创| 标签: Swagger API文档生成 spring集成 文档工具
Swagger简介
Swagger是当前最好用的Restful API文档生成的开源项目,实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,同时swagger-ui还可以测试spring restful风格的接口功能。
本文档只介绍项目中使用spring 3.2.10版本集成和注意事项(遇到了一些坑)。
SpringBoot项目(4.0以上版本)与swagger2集成相对比较简单,可以自己百度搜索。
项目环境介绍
· JDK 1.8
· Spring 3.2.10
· swagger-springmvc 1.0.2
集成swagger步骤
第一步 引入jar包
<!-- swagger start -->
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-models</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.wordnik</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.3.11</version>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>15.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml</groupId>
<artifactId>classmate</artifactId>
<version>1.1.0</version>
</dependency>
<!-- swagger end -->
由于项目中已经集成过jackson的jar包 (参考文档链接)根据具体情况添加
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.4.4</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.4.4</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>2.4.4</version>
第二部 swaggerconfig配置类
新建了一个包名
Swagger的配置实际上就是自定义一个Config类,通过java编码的方式实现配置
package com.zxq.iov.cloud.sp.as.web.config;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
/**
*
* @author Administrator
* /sp-as-web/src/main/java/com/zxq/iov/cloud/sp/as/web/config/SwaggerConfig.java
*/
@EnableSwagger
public class SwaggerConfig {
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)
.apiInfo(apiInfo())
.includePatterns(".*?");
}
private ApiInfo apiInfo(){
ApiInfo apiInfo = new ApiInfo(
"springmvc swagger",
"spring-API swagger",
"My Apps API terms of service",
"",
"web app",
"My Apps API License URL");
return apiInfo;
}
}
第三步 在spring-mvc.xml中配置bean
维保模块项目是zxq-servlet.xml
<!-- swagger start -->
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
<bean class="com.zxq.iov.cloud.sp.as.web.config.SwaggerConfig" />
<!— swagger-ui文件的的过滤 -->
<mvc:resources mapping="/swagger/**" location="/swagger/"/>
<!-- swagger end -->
第四步 Swagger-UI配置
Swagger扫描解析得到的是一个json文档,对于用户不太友好。下面介绍swagger-ui,它能够友好的展示解析得到的接口说明内
首先去Swagger-UI官网git下载版本2.10的,别下载3.0以上的,否则就出现坑爹的现象,你的页面始终是No operations defined in spec!,
像这样,急死人
1)Swagger-UI的git地址:https://github.com/swagger-api/swagger-ui/tree/v2.2.10
下载这里面的dist文件夹,把文件夹整个拷贝到你项目工程的webapp下
2)找到dist文件夹下的index.html文件,把大概第40行的url改成url = “http://localhost:8080/项目名称/api-docs”;注意这个api-docs是固定的,不要改!
获取其所有的 dist 目录下东西放到需要集成的项目里,本文放入 src/main/webapp /swagger/ 目录下。
修改swagger/index.html文件,默认是从连接http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON,这里需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式,{}中的值根据自身情况填写。
比如我的url值为:http://localhost:8083/sp-as/api-docs
第五步 web.xml的修改
统一登录过滤的设置
<filter>
<filter-name>casAuthenticationFilter</filter-name>
<filter-class>org.jasig.cas.client.authentication.AuthenticationFilter</filter-class>
<init-param>
<param-name>ignorePattern</param-name>
<param-value>/swagger/*|/api-docs/*</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>casAuthenticationFilter</filter-name>
<url-pattern>*.html</url-pattern>
</filter-mapping>
参考文档链接
https://www.oschina.net/question/2548090_2160781
https://blog.csdn.net/gyb_csdn/article/details/75123575
本文作者:薛沉沉