KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #open-source #agent-skills #ai #dsh-plugin #llm #windows

swagger

★ 98 Open GitHub ↗

快速生成可测试的web接口文档的类库

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# swagger4j
从版本2.0.0开始，`cpj-swagger`更名为`swagger4j`，顶级包名也更名为com.cpjit.swagger4j，与版本1.x.x 完全不兼容。<br />
`swagger4j`通过与[`swagger ui`](http://swagger.io/)一起快速为您的web项目产生接口文档，并且支持在线测试接口。`swagger4j`可以很方便的与`struts2`、`spring mvc`、`servlet`集成使用，下面的教程将详细说明如何使用swagger4j。

## 目录
[`一. 运行要求`](#一-运行要求)<br />
[`二. 加入依赖JAR文件`](#二-加入依赖JAR文件)<br />
[`三. 配置`](#三-配置)<br />
[`四. 标注你的接口`](#四-标注你的接口)<br />
[`五. 访问接口文档`](#五-访问接口文档)<br />
[`六. 核心API`](#六-核心api)<br />
[`七. 示例程序`](#七-示例程序)<br />

## 一. 运行要求
JDK1.8+

## 二. 加入依赖JAR文件
* maven：
```xml
<dependency>
	<groupId>com.cpjit</groupId>
	<artifactId>swagger4j</artifactId>
	<version>2.2.0</version>
</dependency>
```

## 三. 配置
### 1. 选择使用方式
您可以通过三种方式来使用`swagger4j`。
* 与strut2、SpringMVC、Servlet集成</br>
如果您的web项目是基于`strut2`或`SpringMVC`或`servlet`的，您可以在您的web.xml文件中加入如下代码来快速集成`swagger4j`：
```xml
   <filter>
      <filter-name>swaggerFilter</filter-name>
      <filter-class>com.cpjit.swagger4j.SwaggerFilter</filter-class>
   </filter>
   <filter-mapping>
      <filter-name>swaggerFilter</filter-name>
      <url-pattern>/doc/*</url-pattern>
   </filter-mapping>
```
* 与spring-boot集成 </br>
如果您的项目是基于`spring-boot`的，您可以创建一个配置类来快速集成`swagger4j`：
```java
@Configuration
public class SwaggerConfig {
    @Bean
    public FilterRegistrationBean swaggerFilter() {
        FilterRegistrationBean bean = new FilterRegistrationBean();
        SwaggerFilter filter = new SwaggerFilter();
        bean.setFilter(filter);
        bean.setUrlPatterns(Collections.singletonList("/doc/*"));
        return bean;
    }
}
```
### 2. 修改配置项
您需要在项目的源文件目录下添加一个`swagger.properties`文件，并加入以下配置项：
```properties
packageToScan=com.cpjit.swagger4j.action
apiDescription=Swagger Demo
apiTitle=Swagger Demo
apiVersion=1.0.0
teamOfService=www.cpj.com
devMode=true
```
`swagger4j`的配置信息都必须写在`swagger.properties`文件里面。具体的配置项及其说明如下：
<table>
	<thead>
		<tr><th>键</th><th>说明</th><th>支持版本</th></tr>
	</thead>
	<tbody>
		<tr><th>apiFile</th><th>扫描生成json文件的存放路径</th><th></th></tr>
		<tr><th>packageToScan</th><th>扫描的包</th><th></th></tr>
		<tr><th>apiDescription</th><th>接口文档描述</th><th></th></tr>
		<tr><th>apiTitle</th><th>接口文档标题</th><th></th></tr>
		<tr><th>apiVersion</th><th>接口版本</th><th></th></tr>
		<tr><th>teamOfService</th><th>服务团队</th><th></th></tr>
		<tr><th>apiHost</th><th>接口主机地址</th><th></th></tr>
		<tr><th>apiBasePath</th><th>接口基路径</th><th></th></tr>
		<tr><th>devMode</th><th>是否启用开发模式，如果开启则每次获取接口文档的时候都会扫描类</th><th></th></tr>
		<tr><th>suffix</th><th>接口请求地址后缀，如.action</th><th></th></tr>
		<tr><th>disabled</th><th>是否关闭swagger4j，一般用于生产环境</th><th></th></tr>
		<tr><th>schemes</th><th>支持的请求协议，如http、https</th><td>v2.1.4+</td></tr>
	</tbody>
</table>

## 四. 标注你的接口
接下来需要用swagger4j提供的注解来标明你的接口，下面以spring mvc为例来说明如何标注接口，其他方式请参考[`示例程序`](#六-示例程序下载)。
```java
@Controller
@APIs("/demo")
@RequestMapping("/demo")
public class DemoController {
	@API(value="login", summary="示例1", parameters={
			@Param(name="username", description="用户名", type="string"),
			@Param(name="password", description="密码", type="string", format="password"),
			@Param(name="image" , description="图片", type="file", format="binary")
	})
	@RequestMapping(value="login", method=RequestMethod.POST)
	public void login(HttpServletResponse response, String username, String password, MultipartFile image)
												throws Exception {
		response.setContentType("application/json;charset=utf-8");
		JSONWriter writer = new JSONWriter(response.getWriter());
		Map<String, String> user = new HashMap<String, String>();
		user.put("username", username);
		user.put("password", password);
		writer.writeObject(user);
		writer.flush();
		writer.close();
	}
}
```
## 五. 访问接口文档
在完成前面的工作之后，您可以部署好您的web项目，然后在浏览器输入以下地址就可以访问接口文档了：
http://127.0.0.1:8080/您的项目名/doc/index.html

## 六. 核心API
### 1. 注解 @com.cpjit.swagger4j.annotation.APIs
该注解放在一个类上面，用来表明类中包含作为HTTP接口的方法（被注解[`@com.cpjit.swagger4j.annotation.API`](#2-注解-comcpjitswagger4jannotationapi)标注了的方法）。
该注解的`value`用来设置接口的前缀，这和`struts2`的命名空间很像。使用示例如下：
```java
@APIs("/demo")
public class DemoController {
  
}
```
### 2. 注解 @com.cpjit.swagger4j.annotation.API
该注解放在一个方法上面，用来表明方法是HTTP接口方法，注解的属性说明如下：
#### `value`
与注解[`@com.cpjit.swagger4j.annotation.APIs`](#1-注解-comcpjitswagger4jannotationapis)的`value`属性一起来指定接口的地址，例如有如下设置：
```java
@APIs("/demo")
public class DemoController {
  	@API(value="login"})
	public void login()
	}
}
```
那么`login`方法对应的接口地址为： youhost/demo/login

#### `parameters`
用来指定接口的请求参数，详情参见注解[`Param`](#3-注解-comcpjitswagger4jannotationparam)的说明。
#### `summary`
接口功能简述。
#### `description`
接口功能详细说明。
#### `method`
请求方式，默认是POST。
#### `consumes`

允许的请求MIME，比如：multipart/form-data、application/xml、application/json默认是application/json; charset=utf-8。
</br>特别说明：</br>
当为 `multipart/form-data` 时，[`Param`](#3-注解 @comcpjitswagger4jannotationparam)
的[`in`](#in)属性必须为`formData`，但是[`in`](#in)为path、header时[`Param`](#3-注解-comcpjitswagger4jannotationparam)不用遵循此规则。
#### `deprecated`
1.2.2引入的新属性，表示接口是否已经被废弃，默认是false。
#### `hide`
1.2.2引入的新属性，表示是否隐藏接口。
### 3. 注解 @com.cpjit.swagger4j.annotation.Param
用来说明请求参数，例如：
```java
@API(value="login", summary="示例1", parameters={
		@Param(name="username", description="用户名", type="string"),
		@Param(name="password", description="密码", type="string", format="password")})
@RequestMapping(value="login", method=RequestMethod.POST)
public void login(HttpServletResponse response, String username, String password) throws Exception {
}
```
这表明该接口需要两个请求参数，及`username`、`password`。
注解`@com.cpjit.swagger4j.annotation.Param`的属性说明如下：
#### `name`
参数名
#### `in`
输入参数类型，可取如下值：
<ul>
  <li>query - 参数拼接到url中</li>
  <li>body - 参数直接放入请求体中</li>
  <li>operation - restful风格的参数传递</li>
  <li>header - 参数放在请求头中</li>
  <li>formData - 参数通过form表单提交</li>
 </ul> 
特别说明：
<ul>
 <li>当前请求方式为POST的时候，默认值为formData</li>
 <li>请求方式为非POST的时候，默认值为query</li>
</ul>

#### ~~`type`~~ 
数据类型, 与[`format`](#format)一起指定请求参数的数据类型。
	 `type` 和 `format` 的可选值如下：
	 
<table border="0" cellpadding="1" cellspacing="0">
		<thead>
		<tr bgcolor="#EFEFEF" style="border: 1px solid #cccccc;">
		<th align="left">通用名</th>
		<th align="left"><a href="#dataTypeType"><code>type</code></a></th>
		<th align="left"><a href="#dataTypeFormat"><code>format</code></a></th>
		<th align="left">备注</th>
		</tr>
		</thead>
		<tbody>
		<tr bgcolor="#FFFFFF">
		<td>integer</td>
		<td><code>integer</code></td>
		<td><code>int32</code></td>
		<td>signed 32 bits</td>
		</tr>
		<tr bgcolor="#EFEFEF">
		<td>long</td>
		<td><code>integer</code></td>
		<td><code>int64</code></td>
		<td>signed 64 bits</td>
		</tr>
		<tr bgcolor="#FFFFFF">
		<td>float</td>
		<td><code>number</code></td>
		<td><code>float</code></td>
		<td></td>
		</tr>
		<tr bgcolor="#EFEFEF">
		<td>double</td>
		<td><code>number</code></td>
		<td><code>double</code></td>
		<td></td>
		</tr>
		<tr bgcolor="#FFFFFF">
		<td>string</td>
		<td><code>string</code></td>
		<td></td>
		<td></td>
		</tr>
		<tr bgcolor="#EFEFEF">
		<td>byte</td>
		<td><code>string</code></td>
		<td><code>byte</code></td>
		<td>base64 encoded characters</td>
		</tr>
		<tr bgcolor="#FFFFFF">
		<td>binary</td>
		<td><code>string</code></td>
		<td><code>binary</code></td>
		<td>any sequence of octets</td>
		</tr>
		<tr bgcolor="#EFEFEF">
		<td>boolean</td>
		<td><code>boolean</code></td>
		<td></td>
		<td></td>
		</tr>
		<tr bgcolor="#FFFFFF">
		<td>date</td>
		<td><code>string</code></td>
		<td><code>date</code></td>
		<td>As defined by <code>full-date</code> - <a href="http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14">RFC3339</a></td>
		</tr>
		<tr bgcolor="#EFEFEF">
		<td>dateTime</td>
		<td><code>string</code></td>
		<td><code>date-time</code></td>
		<td>As defined by <code>date-time</code> - <a href="http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14">RFC3339</a></td>
		</tr>
		<tr bgcolor="#FFFFFF">
		<td>password</td>
		<td><code>string</code></td>
		<td><code>password</code></td>
		<td>Used to hint UIs the input needs to be obscured.</td>
		</tr>
		</tbody>
   </table>
   
#### ~~`format`~~
数据格式，[`type`](#type)一起指定请求参数的数据类型。
#### `dataType`
1.2.2引入的新属性，替代`type`和`format`来指定数据类型。
#### description
参数说明
#### `required`
是否是必须参数， 默认是false
### `defaultValue`
2.1.0引入的新属性，用于指定参数的默认值。
### 4.枚举 com.cpjit.swagger4j.annotation.DataType
可用的数据类型

## 七. 示例程序
* [`Spring MVC`](https://github.com/cpjit/swagger-demo-springmvc)

swagger

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README