一：Swagger介绍
Swagger是当前最好用的Restful API文档生成的开源项目，通过swagger-spring项目
实现了与SpingMVC框架的无缝集成功能，方便生成spring restful风格的接口文档，
同时swagger-ui还可以测试spring restful风格的接口功能。
二：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.启动项目 http://localhost:8080/三、常见swagger注解一览与使用最常用的5个注解
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
其它若干
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit
四、关键代码和实际例子例子1：[java]view plain copy @ApiOperation(value="获得用户列表",notes="列表信息",httpMethod="POST",produces=MediaType.APPLICATION_JSON_VALUE)@ResponseBody@RequestMapping(value="list",method=RequestMethod.POST)publicResult<User>list(@ApiParam(value="分类ID",required=true)@RequestParamLongcategoryId,@ApiParam(value="token",required=true)@RequestParamStringtoken){Result<User>result=newResult<User>();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*/)publicResult<String>update(Useruser){Stringu=findUser(user);System.out.println(u);returnnull;} 当参数太多的时候，需要定义太多的参数，排版看起来很不舒服。 这个时候，可以使用对象来接收。 @ApiModel(value="用户对象",description="user2") publicclassUserextendsCommonParam{} Web前端/移动端HTTP请求方式：直接把参数附带到URL后面，或者用AJAX方法，表单提交。
这里面存在一个小问题，当后端用对象User来接收参数的时候，Swagger自带的工具是这样的： 这种形式，并不是表单提交，或者把参数附加到URL的后面。 我们只能手动构造URL，附带参数去提交。 如果需要测试的话！ 例子3： publicResult<String>add(@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)publicResult<User>list(@ApiParam(value="分类ID",required=true)@RequestParamLongcategoryId,@ApiParam(value="分类ID",required=true)@RequestParamLongcategoryId2,@ApiParam(value="token",required=true)@RequestParamStringtoken){Result<User>result=newResult<User>();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对象//只能手动调用方法publicResult<String>add(@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)publicResult<String>update(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@EnableSwaggerpublicclassCustomJavaPluginConfigextendsWebMvcConfigurerAdapter{privateSpringSwaggerConfigspringSwaggerConfig;@AutowiredpublicvoidsetSpringSwaggerConfig(SpringSwaggerConfigspringSwaggerConfig){this.springSwaggerConfig=springSwaggerConfig;}/***链式编程来定制API样式后续会加上分组信息**@return*/@BeanpublicSwaggerSpringMvcPlugincustomImplementation(){returnnewSwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(".*").useDefaultResponseMessages(false)//.pathProvider(newGtPaths()).apiVersion("0.1").swaggerGroup("user");}privateApiInfoapiInfo(){ApiInfoapiInfo=newApiInfo("小雷移动端API接口平台","提供详细的后台所有Restful接口","/FansUnion","FansUnion@","小雷博客","/FansUnion");returnapiInfo;}@OverridepublicvoidconfigureDefaultServletHandling(DefaultServletHandlerConfigurerconfigurer){configurer.enable();}classGtPathsextendsSwaggerPathProvider{@OverrideprotectedStringapplicationPath(){return"/restapi";}@OverrideprotectedStringgetDocumentationPath(){return"/restapi";}}}
如果觉得《Spring MVC中使用Swagger生成API文档和完整项目示例Demo swagger-server-api（二十）》对你有帮助，请点赞、收藏，并留下你的观点哦！
