# unified-swagger

**Repository Path**: pesking/unified-swagger

## Basic Information

- **Project Name**: unified-swagger
- **Description**: 统一swagger模块
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-12-10
- **Last Updated**: 2025-11-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

### ## 统一Swagger使用说明



#### 1、使用XML方式配置API接口

#### 1.1 目的

​	使用swagger注解配置API接口存在配置难度，开发人员熟悉程度不一样，导致swagger反馈的结果不一样，大部分出现配置不全。

​	使用XML方式配置比较简单，不需要了解swagger的注解，只需要按照XML规范的格式定义即可

​	使用XML方式配置后容易生成接口文档

​	使用XML方式配置后可以生成模拟接口，配置完成即可生成模拟数据

#### 1.2 使用说明

XML存放目录，XML必须存在在/resources/config/api/下，可以建多个子目录

![image-20240405223252725](./assets/image-20240405223252725.png)

XML配置全影

```XML
<?xml version="1.0" encoding="UTF-8" ?>
<api desc="测试示例" mappingAddress="/test2/12345678">
    <parameter-list>
        <parameter name="param1" label="参数1"/>
    </parameter-list>
    <handle-list>
        <handle id="data" rowCount="2">
            <resultColumn>
                <column name="a" title="结果A" type="int" min="0" max="10"/>
                <column name="b" title="结果B" type="long"/>
                <column name="c" title="结果C" type="double"/>
                <column name="d" title="结果D" type="float"/>
                <column name="e" title="结果e" type="date"/>
                <column name="f" title="结果F" type="time"/>
                <column name="g" title="结果G" type="timestamp"/>
                <complexColumn name="h" title="结果G">
                    <handle>
                        <resultColumn>
                            <column name="id" title="ID"/>
                            <column name="name" title="name"/>
                        </resultColumn>
                    </handle>
                </complexColumn>
            </resultColumn>
            <staticJsonData><![CDATA[
                {
                    "a": 1,
                    "b": 10,
                    "c": 11,
                    "d": 12,
                    "e": "2024-04-12",
                    "f": "11:00:00",
                    "g": "2024-04-17 12:12:12",
                    "h": [{
                            "id": 1,
                            "name": "name1"
                        },
                        {
                            "id": 2,
                            "name": "name2"
                        }
                    ]
                }
            ]]></staticJsonData>
        </handle>
    </handle-list>
</api>
```

数据类型说明

```tex
INT("INT","整形数字")
,LONG("LONG","长整形数字")
,FLOAT("FLOAT","单精度数字")
,DOUBLE("DOUBLE","双精度数字")
,DATE("DATE","日期(YYYY-MM-DD)")
,TIME("TIME","时间(HH:MI:SS)")
,TIMESTAMP("TIMESTAMP","日期时间(YYYY-MM-DD HH:MI:SS)")
,STRING("STRING","字符串")
,FILE("FILE","文件类型")
,PHONE("PHONE","手机号")
,EMAIL("EMAIL","电子邮箱")
,IC("IC","身份证")
,TELEPHONE("TELEPHONE","电话号码")
,QQ("QQ","QQ号码")
,ZIP("ZIP","邮编")
,URL("URL","URL")
,MSN("MSN","MSN")
,CLASS("CLASS","类名")
,REG("REG","正则表达式")
,JSON("JSON","JSON")
,JSONARRAY("JSONARRAY","jsonArray")
,XML("XML","XML")
,PASSWORD("PASSWORD","密码");
```

#### 1.3 示例说明

##### 1.3.1 示例一

```
<?xml version="1.0" encoding="UTF-8" ?>
<api desc="获取当前用户信息" tags="授权管理"
        mappingAddress="/auth-center/auth/currentUser"
        dataNodeName="data"
     outputSimulatedData="false">
    <parameter-list>
        <parameter name="systemId" label="系统ID" outputSimulatedData="false"/>
    </parameter-list>
    <handle-list>
        <handle id="currentUser" isOutputObject="true">
            <resultColumn>
                <column name="userId" title="用户ID"/>
                <column name="nickName" title="用户昵称"/>
                <column name="userName" title="用户名"/>
                <column name="userType" title="用户类型" staticData="admin,normal"/>
                <column name="userTypeName" title="用户类型名" staticData="超级管理用户,普通用户"/>
                <column name="loginName" title="登录名"/>
                <column name="phoneNumber" title="手机号" type="phone"/>
                <column name="email" title="电子邮箱" type="email"/>
                <column name="admin" title="是否为超级管理员" staticData="1,0"/>
                <complexColumn name="orgInfo" title="组织信息">
                    <handle isOutputObject="true">
                        <resultColumn>
                            <column name="id" title="ID"/>
                            <column name="code" title="组织代码"/>
                            <column name="name" title="组织名"/>
                            <column name="type" title="类型"/>
                            <column name="typeName" title="类型名"/>
                            <column name="fullName" title="组织全称"/>
                            <column name="logo" title="组织LOGO"/>
                        </resultColumn>
                    </handle>
                </complexColumn>
                <complexColumn name="deptInfo" title="部门信息">
                    <handle isOutputObject="true">
                        <resultColumn>
                            <column name="id" title="ID"/>
                            <column name="code" title="组织代码"/>
                            <column name="name" title="组织名"/>
                            <column name="type" title="类型"/>
                            <column name="typeName" title="类型名"/>
                            <column name="fullName" title="组织全称"/>
                            <column name="logo" title="组织LOGO"/>
                        </resultColumn>
                    </handle>
                </complexColumn>
                <complexColumn name="extendData" title="扩展数据">
                    <handle rowCount="2">
                        <resultColumn>
                            <column name="value" title="扩展值"/>
                            <column name="name" title="扩展名"/>
                        </resultColumn>
                    </handle>
                </complexColumn>
            </resultColumn>
        </handle>
    </handle-list>
</api>
```

输出swagger结果

![image-20240405223439697](./assets/image-20240405223439697.png)

## 2. 自定义文档
  可以自定义文档，通过swagger界面展示出来，只需要resources/static目录下新建一个readme.md文件,在此文档编写文档说明
## 3、功能说明 
##### 1）未定义swagger注解的路径自动过滤掉，不在swagger页面上显示

  标签tag中不含有中文的，认为未配置swagger注解，被过滤掉