swagger
本文作者：小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119 实际项目中非常需要写文档，提高Java服务端和Web前端以及移动端的对接效率。 听说Swagger这个工具，还不错，就网上找了些资料，自己实践了下。一：Swagger介绍Swagger是当前最好用的Restful API文档生成的...
·
实际项目中非常需要写文档，提高Java服务端和Web前端以及移动端的对接效率。
听说Swagger这个工具，还不错，就网上找了些资料，自己实践了下。
一：Swagger介绍
Swagger是当前最好用的Restful API文档生成的开源项目，通过swagger-spring项目
实现了与SpingMVC框架的无缝集成功能，方便生成spring restful风格的接口文档，
同时swagger-ui还可以测试spring restful风格的接口功能。
官方网站为：http://swagger.io/
二：Swagger与Spring MVC集成步骤
1.Maven关键配置
-
<dependency>
-
<groupId>com.mangofactory
</groupId>
-
<artifactId>swagger-springmvc
</artifactId>
-
<version>1.0.2
</version>
-
</dependency>
-
-
<dependency>
-
<groupId>org.springframework
</groupId>
-
<artifactId>spring-webmvc
</artifactId>
-
<version>4.1.6.RELEASE
</version>
-
</dependency>
2. 插件配置
CustomJavaPluginConfig
3.复制swagger的相关js等静态资源到webapp目录。
swagger-ui.js之类的。
我copy过一次，但是有问题，最后从网上下载了一个项目，可以直接用的那种。
然后自己再逐步改造。
4.启动项目
三、常见swagger注解一览与使用
最常用的5个注解
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
其它若干
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit
四、关键代码和实际例子
例子1：
-
@ApiOperation(value =
"获得用户列表", notes =
"列表信息", httpMethod =
"POST", produces = MediaType.APPLICATION_JSON_VALUE)
-
@ResponseBody
-
@RequestMapping(value =
"list", method = RequestMethod.POST)
-
public Result<User> list(
-
@ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
-
@ApiParam(value = "token", required = true) @RequestParam String token) {
-
Result<User> result =
new Result<User>();
-
User user =
new User();
-
result.setData(user);
-
return result;
-
}
@ApiParam(value = "token", required = true) @RequestParam String token
Web前端/移动端HTTP请求方式：直接把参数附带到URL后面，或者用AJAX方法，表单提交。
例子2：
-
@ApiOperation(value =
"update用户", notes =
")", httpMethod =
"POST", produces = MediaType.APPLICATION_JSON_VALUE)
-
@ResponseBody
-
@RequestMapping(value =
"update", method = RequestMethod.GET
/*,produces = MediaType.APPLICATION_FORM_URLENCODED_VALUE*/)
-
public Result<String> update(User user) {
-
String u = findUser(user);
-
System.out.println(u);
-
return
null;
-
}
当参数太多的时候，需要定义太多的参数，排版看起来很不舒服。
这个时候，可以使用对象来接收。
@ApiModel(value = "用户对象",description="user2")
public class User extends CommonParam{
}
Web前端/移动端HTTP请求方式：直接把参数附带到URL后面，或者用AJAX方法，表单提交。
这里面存在一个小问题，当后端用对象User来接收参数的时候，Swagger自带的工具是这样的：
这种形式，并不是表单提交，或者把参数附加到URL的后面。
我们只能手动构造URL，附带参数去提交。
如果需要测试的话！
例子3：
-
public Result<String> add(@RequestBody User user) {
-
String u = findUser(user);
-
System.out.println(u);
-
return
null;
-
}
Web前端/移动端HTTP请求方式：必须把参数，放到request请求的body中去。
后端不能直接用request.getParam("token")这种。
获得request body中的数据，手动转换成目标数据。
String charReader(HttpServletRequest request) throws IOException {
BufferedReader br = request.getReader();
String str, wholeStr = "";
while ((str = br.readLine()) != null) {
wholeStr += str;
}
return wholeStr;
}
个人推荐：
1.参数不多的时候，用例子1，用@ApiParam注解生成文档。
swagger可视化界面，可以直接设置参数，发送请求来测试
2.参数比较多的时候，用例子2，用对象来接收参数，在对象里针对每个字段，@ApiModelProperty注解生成文档。
swagger可视化界面，可以直接设置参数，但是无法接收到。
因此，推荐使用其它HTTP请求或POST模拟工具，发送请求，模拟测试。
不推荐例子3，不通用，局限性比较大。
五、若干截图
六、源代码
-
package cn.fansunion.swagger.serverapi.controller;
-
-
import org.springframework.http.MediaType;
-
import org.springframework.stereotype.Controller;
-
import org.springframework.web.bind.annotation.RequestBody;
-
import org.springframework.web.bind.annotation.RequestMapping;
-
import org.springframework.web.bind.annotation.RequestMethod;
-
import org.springframework.web.bind.annotation.RequestParam;
-
import org.springframework.web.bind.annotation.ResponseBody;
-
-
import com.wordnik.swagger.annotations.Api;
-
import com.wordnik.swagger.annotations.ApiOperation;
-
import com.wordnik.swagger.annotations.ApiParam;
-
-
/**
-
* 小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
-
* 博客：http://blog.csdn.net/fansunion
-
*
-
*/
-
@Api(value =
"user", description =
"用户管理", produces = MediaType.APPLICATION_JSON_VALUE)
-
@Controller
-
@RequestMapping(
"user")
-
public
class UserController {
-
-
// 列出某个类目的所有规格
-
@ApiOperation(value =
"获得用户列表", notes =
"列表信息", httpMethod =
"POST", produces = MediaType.APPLICATION_JSON_VALUE)
-
@ResponseBody
-
@RequestMapping(value =
"list", method = RequestMethod.POST)
-
public Result<User> list(
-
@ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
-
@ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId2,
-
@ApiParam(value = "token", required = true) @RequestParam String token) {
-
Result<User> result =
new Result<User>();
-
User user =
new User();
-
result.setData(user);
-
return result;
-
}
-
-
@ApiOperation(value =
"添加用户", notes =
"获取商品信息(用于数据同步)", httpMethod =
"POST", produces = MediaType.APPLICATION_JSON_VALUE)
-
@ResponseBody
-
@RequestMapping(value =
"add", method = RequestMethod.POST)
-
// @RequestBody只能有1个
-
// 使用了@RequestBody，不能在拦截器中，获得流中的数据，再json转换，拦截器中，也不清楚数据的类型，无法转换成java对象
-
// 只能手动调用方法
-
public Result<String> add(@RequestBody User user) {
-
String u = findUser(user);
-
System.out.println(u);
-
return
null;
-
}
-
-
@ApiOperation(value =
"update用户", notes =
"获取商品信息(用于数据同步)", httpMethod =
"POST", produces = MediaType.APPLICATION_JSON_VALUE)
-
@ResponseBody
-
@RequestMapping(value =
"update", method = RequestMethod.GET)
-
public Result<String> update(User user) {
-
String u = findUser(user);
-
System.out.println(u);
-
return
null;
-
}
-
-
private String findUser(User user) {
-
String token = user.getToken();
-
return token;
-
}
-
}
-
package cn.fansunion.swagger.serverapi.controller;
-
-
import com.wordnik.swagger.annotations.ApiModel;
-
import com.wordnik.swagger.annotations.ApiModelProperty;
-
-
/**
-
* 小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
-
* 博客：http://blog.csdn.net/fansunion
-
*
-
*/
-
@ApiModel(value =
"用户对象", description =
"user2")
-
public
class User extends CommonParam {
-
-
@ApiModelProperty(value =
"商品信息", required =
true)
-
private String name;
-
@ApiModelProperty(value =
"密码", required =
true)
-
private String password;
-
-
@ApiModelProperty(value =
"性别")
-
private Integer sex;
-
@ApiModelProperty(value =
"密码", required =
true)
-
private String token;
-
-
public String getToken() {
-
return token;
-
}
-
-
public void setToken(String token) {
-
this.token = token;
-
}
-
-
public String getName() {
-
return name;
-
}
-
-
public void setName(String name) {
-
this.name = name;
-
}
-
-
public String getPassword() {
-
return password;
-
}
-
-
public void setPassword(String password) {
-
this.password = password;
-
}
-
-
public Integer getSex() {
-
return sex;
-
}
-
-
public void setSex(Integer sex) {
-
this.sex = sex;
-
}
-
-
}
-
package cn.fansunion.swagger.serverapi.swagger;
-
-
import org.springframework.beans.factory.annotation.Autowired;
-
import org.springframework.context.annotation.Bean;
-
import org.springframework.context.annotation.Configuration;
-
import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
-
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
-
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
-
-
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
-
import com.mangofactory.swagger.models.dto.ApiInfo;
-
import com.mangofactory.swagger.paths.SwaggerPathProvider;
-
import com.mangofactory.swagger.plugin.EnableSwagger;
-
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
-
-
@Configuration
-
@EnableWebMvc
-
@EnableSwagger
-
public
class CustomJavaPluginConfig extends WebMvcConfigurerAdapter {
-
-
private SpringSwaggerConfig springSwaggerConfig;
-
-
@Autowired
-
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
-
this.springSwaggerConfig = springSwaggerConfig;
-
}
-
-
/**
-
* 链式编程 来定制API样式 后续会加上分组信息
-
*
-
* @return
-
*/
-
@Bean
-
public SwaggerSpringMvcPlugin customImplementation() {
-
return
new SwaggerSpringMvcPlugin(
this.springSwaggerConfig)
-
.apiInfo(apiInfo()).includePatterns(
".*")
-
.useDefaultResponseMessages(
false)
-
// .pathProvider(new GtPaths())
-
.apiVersion(
"0.1").swaggerGroup(
"user");
-
-
}
-
-
private ApiInfo apiInfo() {
-
ApiInfo apiInfo =
new ApiInfo(
"小雷移动端API接口平台",
-
"提供详细的后台所有Restful接口",
"http://blog.csdn.net/FansUnion",
-
"FansUnion@qq.com",
"小雷博客",
"http://blog.csdn.net/FansUnion");
-
return apiInfo;
-
}
-
-
@Override
-
public void configureDefaultServletHandling(
-
DefaultServletHandlerConfigurer configurer) {
-
configurer.enable();
-
}
-
-
class GtPaths extends SwaggerPathProvider {
-
-
@Override
-
protected String applicationPath() {
-
return
"/restapi";
-
}
-
-
@Override
-
protected String getDocumentationPath() {
-
return
"/restapi";
-
}
-
}
-
-
}
七、项目下载地址
八、参考资料
实际项目中非常需要写文档，提高Java服务端和Web前端以及移动端的对接效率。
听说Swagger这个工具，还不错，就网上找了些资料，自己实践了下。
一：Swagger介绍
Swagger是当前最好用的Restful API文档生成的开源项目，通过swagger-spring项目
实现了与SpingMVC框架的无缝集成功能，方便生成spring restful风格的接口文档，
同时swagger-ui还可以测试spring restful风格的接口功能。
官方网站为：http://swagger.io/
二：Swagger与Spring MVC集成步骤
1.Maven关键配置
-
<dependency>
-
<groupId>com.mangofactory
</groupId>
-
<artifactId>swagger-springmvc
</artifactId>
-
<version>1.0.2
</version>
-
</dependency>
-
-
<dependency>
-
<groupId>org.springframework
</groupId>
-
<artifactId>spring-webmvc
</artifactId>
-
<version>4.1.6.RELEASE
</version>
-
</dependency>
2. 插件配置
CustomJavaPluginConfig
3.复制swagger的相关js等静态资源到webapp目录。
swagger-ui.js之类的。
我copy过一次，但是有问题，最后从网上下载了一个项目，可以直接用的那种。
然后自己再逐步改造。
4.启动项目
三、常见swagger注解一览与使用
最常用的5个注解
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
其它若干
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit
四、关键代码和实际例子
例子1：
-
@ApiOperation(value =
"获得用户列表", notes =
"列表信息", httpMethod =
"POST", produces = MediaType.APPLICATION_JSON_VALUE)
-
@ResponseBody
-
@RequestMapping(value =
"list", method = RequestMethod.POST)
-
public Result<User> list(
-
@ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
-
@ApiParam(value = "token", required = true) @RequestParam String token) {
-
Result<User> result =
new Result<User>();
-
User user =
new User();
-
result.setData(user);
-
return result;
-
}
@ApiParam(value = "token", required = true) @RequestParam String token
Web前端/移动端HTTP请求方式：直接把参数附带到URL后面，或者用AJAX方法，表单提交。
例子2：
-
@ApiOperation(value =
"update用户", notes =
")", httpMethod =
"POST", produces = MediaType.APPLICATION_JSON_VALUE)
-
@ResponseBody
-
@RequestMapping(value =
"update", method = RequestMethod.GET
/*,produces = MediaType.APPLICATION_FORM_URLENCODED_VALUE*/)
-
public Result<String> update(User user) {
-
String u = findUser(user);
-
System.out.println(u);
-
return
null;
-
}
当参数太多的时候，需要定义太多的参数，排版看起来很不舒服。
这个时候，可以使用对象来接收。
@ApiModel(value = "用户对象",description="user2")
public class User extends CommonParam{
}
Web前端/移动端HTTP请求方式：直接把参数附带到URL后面，或者用AJAX方法，表单提交。
这里面存在一个小问题，当后端用对象User来接收参数的时候，Swagger自带的工具是这样的：
这种形式，并不是表单提交，或者把参数附加到URL的后面。
我们只能手动构造URL，附带参数去提交。
如果需要测试的话！
例子3：
-
public Result<String> add(@RequestBody User user) {
-
String u = findUser(user);
-
System.out.println(u);
-
return
null;
-
}
Web前端/移动端HTTP请求方式：必须把参数，放到request请求的body中去。
后端不能直接用request.getParam("token")这种。
获得request body中的数据，手动转换成目标数据。
String charReader(HttpServletRequest request) throws IOException {
BufferedReader br = request.getReader();
String str, wholeStr = "";
while ((str = br.readLine()) != null) {
wholeStr += str;
}
return wholeStr;
}
个人推荐：
1.参数不多的时候，用例子1，用@ApiParam注解生成文档。
swagger可视化界面，可以直接设置参数，发送请求来测试
2.参数比较多的时候，用例子2，用对象来接收参数，在对象里针对每个字段，@ApiModelProperty注解生成文档。
swagger可视化界面，可以直接设置参数，但是无法接收到。
因此，推荐使用其它HTTP请求或POST模拟工具，发送请求，模拟测试。
不推荐例子3，不通用，局限性比较大。
五、若干截图
六、源代码
-
package cn.fansunion.swagger.serverapi.controller;
-
-
import org.springframework.http.MediaType;
-
import org.springframework.stereotype.Controller;
-
import org.springframework.web.bind.annotation.RequestBody;
-
import org.springframework.web.bind.annotation.RequestMapping;
-
import org.springframework.web.bind.annotation.RequestMethod;
-
import org.springframework.web.bind.annotation.RequestParam;
-
import org.springframework.web.bind.annotation.ResponseBody;
-
-
import com.wordnik.swagger.annotations.Api;
-
import com.wordnik.swagger.annotations.ApiOperation;
-
import com.wordnik.swagger.annotations.ApiParam;
-
-
/**
-
* 小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
-
* 博客：http://blog.csdn.net/fansunion
-
*
-
*/
-
@Api(value =
"user", description =
"用户管理", produces = MediaType.APPLICATION_JSON_VALUE)
-
@Controller
-
@RequestMapping(
"user")
-
public
class UserController {
-
-
// 列出某个类目的所有规格
-
@ApiOperation(value =
"获得用户列表", notes =
"列表信息", httpMethod =
"POST", produces = MediaType.APPLICATION_JSON_VALUE)
-
@ResponseBody
-
@RequestMapping(value =
"list", method = RequestMethod.POST)
-
public Result<User> list(
-
@ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
-
@ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId2,
-
@ApiParam(value = "token", required = true) @RequestParam String token) {
-
Result<User> result =
new Result<User>();
-
User user =
new User();
-
result.setData(user);
-
return result;
-
}
-
-
@ApiOperation(value =
"添加用户", notes =
"获取商品信息(用于数据同步)", httpMethod =
"POST", produces = MediaType.APPLICATION_JSON_VALUE)
-
@ResponseBody
-
@RequestMapping(value =
"add", method = RequestMethod.POST)
-
// @RequestBody只能有1个
-
// 使用了@RequestBody，不能在拦截器中，获得流中的数据，再json转换，拦截器中，也不清楚数据的类型，无法转换成java对象
-
// 只能手动调用方法
-
public Result<String> add(@RequestBody User user) {
-
String u = findUser(user);
-
System.out.println(u);
-
return
null;
-
}
-
-
@ApiOperation(value =
"update用户", notes =
"获取商品信息(用于数据同步)", httpMethod =
"POST", produces = MediaType.APPLICATION_JSON_VALUE)
-
@ResponseBody
-
@RequestMapping(value =
"update", method = RequestMethod.GET)
-
public Result<String> update(User user) {
-
String u = findUser(user);
-
System.out.println(u);
-
return
null;
-
}
-
-
private String findUser(User user) {
-
String token = user.getToken();
-
return token;
-
}
-
}
-
package cn.fansunion.swagger.serverapi.controller;
-
-
import com.wordnik.swagger.annotations.ApiModel;
-
import com.wordnik.swagger.annotations.ApiModelProperty;
-
-
/**
-
* 小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
-
* 博客：http://blog.csdn.net/fansunion
-
*
-
*/
-
@ApiModel(value =
"用户对象", description =
"user2")
-
public
class User extends CommonParam {
-
-
@ApiModelProperty(value =
"商品信息", required =
true)
-
private String name;
-
@ApiModelProperty(value =
"密码", required =
true)
-
private String password;
-
-
@ApiModelProperty(value =
"性别")
-
private Integer sex;
-
@ApiModelProperty(value =
"密码", required =
true)
-
private String token;
-
-
public String getToken() {
-
return token;
-
}
-
-
public void setToken(String token) {
-
this.token = token;
-
}
-
-
public String getName() {
-
return name;
-
}
-
-
public void setName(String name) {
-
this.name = name;
-
}
-
-
public String getPassword() {
-
return password;
-
}
-
-
public void setPassword(String password) {
-
this.password = password;
-
}
-
-
public Integer getSex() {
-
return sex;
-
}
-
-
public void setSex(Integer sex) {
-
this.sex = sex;
-
}
-
-
}
-
package cn.fansunion.swagger.serverapi.swagger;
-
-
import org.springframework.beans.factory.annotation.Autowired;
-
import org.springframework.context.annotation.Bean;
-
import org.springframework.context.annotation.Configuration;
-
import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
-
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
-
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
-
-
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
-
import com.mangofactory.swagger.models.dto.ApiInfo;
-
import com.mangofactory.swagger.paths.SwaggerPathProvider;
-
import com.mangofactory.swagger.plugin.EnableSwagger;
-
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
-
-
@Configuration
-
@EnableWebMvc
-
@EnableSwagger
-
public
class CustomJavaPluginConfig extends WebMvcConfigurerAdapter {
-
-
private SpringSwaggerConfig springSwaggerConfig;
-
-
@Autowired
-
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
-
this.springSwaggerConfig = springSwaggerConfig;
-
}
-
-
/**
-
* 链式编程 来定制API样式 后续会加上分组信息
-
*
-
* @return
-
*/
-
@Bean
-
public SwaggerSpringMvcPlugin customImplementation() {
-
return
new SwaggerSpringMvcPlugin(
this.springSwaggerConfig)
-
.apiInfo(apiInfo()).includePatterns(
".*")
-
.useDefaultResponseMessages(
false)
-
// .pathProvider(new GtPaths())
-
.apiVersion(
"0.1").swaggerGroup(
"user");
-
-
}
-
-
private ApiInfo apiInfo() {
-
ApiInfo apiInfo =
new ApiInfo(
"小雷移动端API接口平台",
-
"提供详细的后台所有Restful接口",
"http://blog.csdn.net/FansUnion",
-
"FansUnion@qq.com",
"小雷博客",
"http://blog.csdn.net/FansUnion");
-
return apiInfo;
-
}
-
-
@Override
-
public void configureDefaultServletHandling(
-
DefaultServletHandlerConfigurer configurer) {
-
configurer.enable();
-
}
-
-
class GtPaths extends SwaggerPathProvider {
-
-
@Override
-
protected String applicationPath() {
-
return
"/restapi";
-
}
-
-
@Override
-
protected String getDocumentationPath() {
-
return
"/restapi";
-
}
-
}
-
-
}
七、项目下载地址
八、参考资料
权威｜前沿｜技术｜干货｜国内首个API全生命周期开发者社区
更多推荐
0
0- 0
已为社区贡献1条内容
所有评论(0)