代码拉取完成,页面将自动刷新
smart-swagger 改进了原来的swagger-doc,并适配jersey。在原来的基础上增加了相关注释规范
项目 | 代码污染 | 学习成本 | 支持springboot | 功能完善程度 |
---|---|---|---|---|
smart-swagger | java原生注解即可 | 低 | 支持 | 目前功能比较少 |
springfox | 污染比较大 | 高 | 支持 | 完善 |
由于本项目还在构建中,所以没有扔到mvncenter,所以先通过mvn install 到本地仓库即可
cd smart-swagger
mvn install
<dependency>
<groupId>com.jay</groupId>
<!--jersey版本-->
<artifactId>swagger-jersey</artifactId>
<!--jfinal版本-->
<!--<artifactId>swagger-jfinal</artifactId>-->
<!--springMVC版本-->
<!--<artifactId>swagger-springMVC</artifactId>-->
<version>1.3-SNAPSHOT</version>
</dependency>
@EnableSwaggerDoc
public class SampleApplication {
public static void main(String[] args) {
SpringApplication springApplication = new SpringApplication(SampleApplication.class);
springApplication.run(args);
}
@Bean
public FilterRegistrationBean logFilterRegistrationBean() {
FilterRegistrationBean filterRegistrationBean = new FilterRegistrationBean();
filterRegistrationBean.setFilter(new FilterInterceptor());
filterRegistrationBean.setName("logFilterRegistrationBean");
filterRegistrationBean.setUrlPatterns(Arrays.asList("/*"));
filterRegistrationBean.setOrder(1);
return filterRegistrationBean;
}
@Bean
public SwaggerDoc swaggerDoc() {
Contact contact = new Contact();
Info info = new Info();
info.setTitle("测试文档");
contact.setEmail("542467660@qq.com");
contact.setName("wk");
contact.setUrl("http://git.oschina.net/wangkang_daydayup/swagger-doc");
info.setDescription("swagger-doc解决了springfox用注解污染代码的问题,采用原生java-doc来实现文档的生成,让代码更加干净,学习成本更低");
info.setContact(contact);
return new SwaggerDoc.SwaggerDocBuilder().addSkipAnnotations(SessionAttribute.class).withDoc("doc")
.withSchemes(Scheme.HTTP)
.withDoc("测试文档").withInfo(info).withHost("139.224.35.224")
.addIgnoreControllers("swaggerController", "basicErrorController").build();
}
}
<beans>
<bean class="com.jay.swagger.web.JerseySwaggerServiceImpl" id="swaggerService"/>
<bean id="beanConfig" class="com.jay.swagger.config.SwaggerInfo" init-method="init">
<property name="schemes">
<util:list value-type="io.swagger.models.Scheme">
<value>HTTP</value>
</util:list>
</property>
<!-- 扫描源码的文件夹位置,当前项目运行可以不用配置,tomcat部署,需要配置,否则找不到源码,扫描不到注释内容 -->
<property name="resources">
<util:list>
<value>E:\\Idea\\api-doc\\smart-swagger\\sample\\jersey2-swagger\\src\\main\\java</value>
</util:list>
</property>
<!-- 在resources配置的文件夹中,扫描的包 -->
<property name="resourcePackages">
<util:list value-type="java.lang.String">
<value>com.sf.vmap.order.service</value>
<value>com.sf.vmap.order.response</value>
</util:list>
</property>
<property name="resourceCharset" value="utf-8"></property>
<property name="version" value="2.0.0"></property>
<!-- 使用nginx代理的情况下不需要配置该项 -->
<!--<property name="host" value="localhost:8888"></property>-->
<!--basePath请与Rest的ContextPath值一样-->
<property name="basePath" value="/services"></property>
<property name="title" value="微服务接口文档"></property>
<property name="description" value="这里是描述呢"></property>
<property name="contact" value="jiangmeng.1992@163.com"></property>
<property name="license" value="Apache 2.0"></property>
<property name="licenseUrl" value="http://www.apache.org/licenses/LICENSE-2.0.html"></property>
</bean>
<dubbo:service interface="com.jay.swagger.web.JerseySwaggerService" protocol="rest" ref="swaggerService" document="swagger"/>
</beans>
public class StartSwagger extends HttpServlet {
@Override
public void init(ServletConfig config) throws ServletException {
super.init(config);
SwaggerDoc swaggerDoc = new SwaggerDoc.SwaggerDocBuilder()
.withTitle("测试文档")
.withHost("localhost:8081")
.withBasePath("/api")
.withContact("jiangmang.1992@163.com")
.withSchemes(Scheme.HTTP)
.withDescription("这是一个测试文档")
.withVersion("2.0.0")
.withScanAll(true)
.withResources("E:\\Idea\\api-doc\\smart-swagger\\sample\\jersey2-swagger\\src\\main\\java")
.withResourcePackages("com.jay.controller","com.jay.domain")
.withResourceCharset("utf-8")
.build();
new SwaggerSourceParse().realParse(swaggerDoc);
}
}
这里是最重要的一点,因为java编译后会把doc擦除,这就是为什么class文件里面很少能看见注释,所以需要利用源码来进行解析,所以需要使用maven插件
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>3.0.1</version>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar-no-fork</goal>
</goals>
</execution>
</executions>
</plugin>
增加复制插件
<plugin>
<artifactId>maven-antrun-plugin</artifactId>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>run</goal>
</goals>
<configuration>
<tasks>
<mkdir dir="${project.basedir}/source"/>
<copy todir="${project.basedir}/source" overwrite="true" >
<fileset dir="${project.build.directory}" erroronmissingdir="false">
<include name="*-sources.jar"/>
</fileset>
</copy>
</tasks>
</configuration>
</execution>
</executions>
</plugin>
下载最新版swagger-ui
https://github.com/swagger-api/swagger-ui 或者 https://gitee.com/cn-src/swagger-document-ui
使用nginx代理接口解决跨域问题
server {
listen 9000;
server_name localhost;
#charset koi8-r;
#access_log logs/host.access.log main;
location / {
root html;
index index.html index.htm;
}
location /services {
proxy_pass http://localhost:8888/services;
}
location /document/services {
proxy_pass http://localhost:8888/services;
}
}
访问:http://10.118.63.128:9000/services/swagger/json 即可得到生成的json文件
用官方链接测试生成的json有无错误
http://petstore.swagger.io/?url=http://10.118.63.128:9000/services/swagger/json
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。