0 Star 2 Fork 0

风吹过的绿洲 / smart-swagger

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
该仓库未声明开源许可证文件(LICENSE),使用请关注具体项目描述及其代码上游依赖。
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README

smart-swagger

smart-swagger 改进了原来的swagger-doc,并适配jersey。在原来的基础上增加了相关注释规范

优点缺点对比

项目 代码污染 学习成本 支持springboot 功能完善程度
smart-swagger java原生注解即可 支持 目前功能比较少
springfox 污染比较大 支持 完善

快速开始

由于本项目还在构建中,所以没有扔到mvncenter,所以先通过mvn install 到本地仓库即可

1.安装到本地仓库

cd smart-swagger
mvn install 

2.项目中使用

<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>

3.spring boot 配置

@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();
    }

}

4.dubbo 配置

<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>

5. servlet(web)项目的配置

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);
    }

}

6. 注释规范

注释规范文档

7. 打包源码

这里是最重要的一点,因为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>

8. 搭建swagger-ui

下载最新版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;
        }
}

9.效果图

10.测试链接

访问: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

空文件

简介

基于swagger的数据接口,通过源码注释生成文档,对源代码不产生任何污染。支持springmvc、springboot、jersey以及jfinal。支持map类型自定义注释注明返回的字段信息。 展开 收起
Java
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
Java
1
https://gitee.com/jay763190097/smart-swagger.git
git@gitee.com:jay763190097/smart-swagger.git
jay763190097
smart-swagger
smart-swagger
master

搜索帮助

14c37bed 8189591 565d56ea 8189591