实际项目中非常需要写文档，提高Java服务端和Web前端以及移动端的对接效率。
听说Swagger这个工具，还不错，就网上找了些资料，自己实践了下。
一：Swagger介绍
Swagger是当前最好用的Restful API文档生成的开源项目，通过swagger-spring项目
实现了与SpingMVC框架的无缝集成功能，方便生成spring restful风格的接口文档，
同时swagger-ui还可以测试spring restful风格的接口功能。
二：Swagger与Spring MVC集成步骤
1.Maven关键配置
com.mangofactory
swagger-springmvc
1.0.2
org.springframework
spring-webmvc
4.1.6.RELEASE
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)
publicResultlist(
@ApiParam(value="分类ID",required=true)@RequestParamLongcategoryId,
@ApiParam(value="token",required=true)@RequestParamStringtoken){
Resultresult=newResult();
Useruser=newUser();
result.setData(user);
returnresult;
}
@ApiParam(value="token",required=true)@RequestParamStringtoken
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*/)
publicResultupdate(Useruser){
Stringu=findUser(user);
System.out.println(u);
returnnull;
}
当参数太多的时候，需要定义太多的参数，排版看起来很不舒服。
这个时候，可以使用对象来接收。
@ApiModel(value="用户对象",description="user2")
publicclassUserextendsCommonParam{
}
Web前端/移动端HTTP请求方式：直接把参数附带到URL后面，或者用AJAX方法，表单提交。
这里面存在一个小问题，当后端用对象User来接收参数的时候，Swagger自带的工具是这样的：
这种形式，并不是表单提交，或者把参数附加到URL的后面。
我们只能手动构造URL，附带参数去提交。
如果需要测试的话！
例子3：
publicResultadd(@RequestBodyUseruser){
Stringu=findUser(user);
System.out.println(u);
returnnull;
}
Web前端/移动端HTTP请求方式：必须把参数，放到request请求的body中去。
后端不能直接用request.getParam("token")这种。
获得request body中的数据，手动转换成目标数据。
StringcharReader(HttpServletRequestrequest)throwsIOException{
BufferedReaderbr=request.getReader();
Stringstr,wholeStr="";
while((str=br.readLine())!=null){
wholeStr+=str;
}
returnwholeStr;
}
个人推荐：
1.参数不多的时候，用例子1，用@ApiParam注解生成文档。
swagger可视化界面，可以直接设置参数，发送请求来测试
2.参数比较多的时候，用例子2，用对象来接收参数，在对象里针对每个字段，@ApiModelProperty注解生成文档。
swagger可视化界面，可以直接设置参数，但是无法接收到。
因此，推荐使用其它HTTP请求或POST模拟工具，发送请求，模拟测试。
不推荐例子3，不通用，局限性比较大。
五、若干截图
六、源代码
packagecn.fansunion.swagger.serverapi.controller;
importorg.springframework.http.MediaType;
importorg.springframework.stereotype.Controller;
importorg.springframework.web.bind.annotation.RequestBody;
importorg.springframework.web.bind.annotation.RequestMapping;
importorg.springframework.web.bind.annotation.RequestMethod;
importorg.springframework.web.bind.annotation.RequestParam;
importorg.springframework.web.bind.annotation.ResponseBody;
importcom.wordnik.swagger.annotations.Api;
importcom.wordnik.swagger.annotations.ApiOperation;
importcom.wordnik.swagger.annotations.ApiParam;
/**
*小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
*博客：/fansunion
*
*/
@Api(value="user",description="用户管理",produces=MediaType.APPLICATION_JSON_VALUE)
@Controller
@RequestMapping("user")
publicclassUserController{
//列出某个类目的所有规格
@ApiOperation(value="获得用户列表",notes="列表信息",httpMethod="POST",produces=MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
@RequestMapping(value="list",method=RequestMethod.POST)
publicResultlist(
@ApiParam(value="分类ID",required=true)@RequestParamLongcategoryId,
@ApiParam(value="分类ID",required=true)@RequestParamLongcategoryId2,
@ApiParam(value="token",required=true)@RequestParamStringtoken){
Resultresult=newResult();
Useruser=newUser();
result.setData(user);
returnresult;
}
@ApiOperation(value="添加用户",notes="获取商品信息(用于数据同步)",httpMethod="POST",produces=MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
@RequestMapping(value="add",method=RequestMethod.POST)
//@RequestBody只能有1个
//使用了@RequestBody，不能在拦截器中，获得流中的数据，再json转换，拦截器中，也不清楚数据的类型，无法转换成java对象
//只能手动调用方法
publicResultadd(@RequestBodyUseruser){
Stringu=findUser(user);
System.out.println(u);
returnnull;
}
@ApiOperation(value="update用户",notes="获取商品信息(用于数据同步)",httpMethod="POST",produces=MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
@RequestMapping(value="update",method=RequestMethod.GET)
publicResultupdate(Useruser){
Stringu=findUser(user);
System.out.println(u);
returnnull;
}
privateStringfindUser(Useruser){
Stringtoken=user.getToken();
returntoken;
}
}
packagecn.fansunion.swagger.serverapi.controller;
importcom.wordnik.swagger.annotations.ApiModel;
importcom.wordnik.swagger.annotations.ApiModelProperty;
/**
*小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
*博客：/fansunion
*
*/
@ApiModel(value="用户对象",description="user2")
publicclassUserextendsCommonParam{
@ApiModelProperty(value="商品信息",required=true)
privateStringname;
@ApiModelProperty(value="密码",required=true)
privateStringpassword;
@ApiModelProperty(value="性别")
privateIntegersex;
@ApiModelProperty(value="密码",required=true)
privateStringtoken;
publicStringgetToken(){
returntoken;
}
publicvoidsetToken(Stringtoken){
this.token=token;
}
publicStringgetName(){
returnname;
}
publicvoidsetName(Stringname){
this.name=name;
}
publicStringgetPassword(){
returnpassword;
}
publicvoidsetPassword(Stringpassword){
this.password=password;
}
publicIntegergetSex(){
returnsex;
}
publicvoidsetSex(Integersex){
this.sex=sex;
}
}
packagecn.fansunion.swagger.serverapi.swagger;
importorg.springframework.beans.factory.annotation.Autowired;
importorg.springframework.context.annotation.Bean;
importorg.springframework.context.annotation.Configuration;
importorg.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
importorg.springframework.web.servlet.config.annotation.EnableWebMvc;
importorg.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
importcom.mangofactory.swagger.configuration.SpringSwaggerConfig;
importcom.mangofactory.swagger.models.dto.ApiInfo;
importcom.mangofactory.swagger.paths.SwaggerPathProvider;
importcom.mangofactory.swagger.plugin.EnableSwagger;
importcom.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
@Configuration
@EnableWebMvc
@EnableSwagger
publicclassCustomJavaPluginConfigextendsWebMvcConfigurerAdapter{
privateSpringSwaggerConfigspringSwaggerConfig;
@Autowired
publicvoidsetSpringSwaggerConfig(SpringSwaggerConfigspringSwaggerConfig){
this.springSwaggerConfig=springSwaggerConfig;
}
/**
*链式编程来定制API样式后续会加上分组信息
*
*@return
*/
@Bean
publicSwaggerSpringMvcPlugincustomImplementation(){
returnnewSwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo()).includePatterns(".*")
.useDefaultResponseMessages(false)
//.pathProvider(newGtPaths())
.apiVersion("0.1").swaggerGroup("user");
}
privateApiInfoapiInfo(){
ApiInfoapiInfo=newApiInfo("小雷移动端API接口平台",
"提供详细的后台所有Restful接口","/FansUnion",
"FansUnion@","小雷博客","/FansUnion");
returnapiInfo;
}
@Override
publicvoidconfigureDefaultServletHandling(
DefaultServletHandlerConfigurerconfigurer){
configurer.enable();
}
classGtPathsextendsSwaggerPathProvider{
@Override
protectedStringapplicationPath(){
return"/restapi";
}
@Override
protectedStringgetDocumentationPath(){
return"/restapi";
}
}
}
如果觉得《swager java_Spring MVC中使用Swagger生成API文档和完整项目示例Demo swagger》对你有帮助，请点赞、收藏，并留下你的观点哦！
