# smart-swagger

**Repository Path**: jay763190097/smart-swagger

## Basic Information

- **Project Name**: smart-swagger
- **Description**: 基于swagger的数据接口，通过源码注释生成文档，对源代码不产生任何污染。支持springmvc、springboot、jersey以及jfinal。支持map类型自定义注释注明返回的字段信息。
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2018-11-15
- **Last Updated**: 2024-08-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# smart-swagger

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

### 优点缺点对比

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


## 快速开始

由于本项目还在构建中，所以没有扔到mvncenter，所以先通过mvn install 到本地仓库即可
### 1.安装到本地仓库
```shell
cd smart-swagger
mvn install 
```
### 2.项目中使用
```xml
<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 配置
```java
@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 配置
```xml
<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)项目的配置 
```java
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. 注释规范

[注释规范文档](./wiki/doc.md)


### 7. 打包源码

这里是最重要的一点，因为java编译后会把doc擦除，这就是为什么class文件里面很少能看见注释，所以需要利用源码来进行解析,所以需要使用maven插件
```xml
 <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>
```
增加复制插件
```xml
<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代理接口解决跨域问题

```editorconfig
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.效果图

<img src="./img/bootstrap_swagger.png"/>

<img src="./img/IMG20181130_175420.png"/>


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