实际项目中非常需要写文档,提高Java服务端和Web前端以及移动端的对接效率。
  听说Swagger这个工具,还不错,就网上找了些资料,自己实践了下。

一:Swagger介绍

Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目

实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,

同时swagger-ui还可以测试spring restful风格的接口功能。

官方网站为:http://swagger.io/

中文网站:http://www.sosoapi.com
二: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";
}
} }
七、项目下载地址
八、参考资料

Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api的更多相关文章

  1. Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api(二十)

    一:Swagger介绍 Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目 实现了与SpingMVC框架的无缝集成功能,方便生成spring r ...

  2. SpringBoot2中,怎么生成静态文档

    SpringBoot2中,怎么生成静态文档 在实际开发过程中,我们通过swagger就可以生成我们的接口文档,这个文档就可以提供给前端人员开发使用的.但是,有时候,我们需要把我们的接口文档,提供给第三 ...

  3. ASP.NET WebAPI使用Swagger生成测试文档

    ASP.NET WebAPI使用Swagger生成测试文档 SwaggerUI是一个简单的Restful API测试和文档工具.简单.漂亮.易用(官方demo).通过读取JSON配置显示API .项目 ...

  4. asp.net core 使用 swagger 生成接口文档

    参考地址:http://www.cnblogs.com/daxnet/p/6181366.html http://www.jianshu.com/p/fa5a9b76f3ed 微软参考文档:https ...

  5. webapi 利用webapiHelp和swagger生成接口文档

    webapi 利用webapiHelp和swagger生成接口文档.均依赖xml(需允许项目生成注释xml) webapiHelp:微软技术自带,仅含有模块.方法.请求-相应参数的注释. swagge ...

  6. PCB DotNetCore Swagger生成WebAPI文档配置方法

    在.net framework框架下可以使用WebApiTestClientWebApi生成WebAPI接口文档与方便接口测试用,而在DotnetCore却没有找到这个工具了,baidu查找一下发现有 ...

  7. api文档设计工具:RAML、Swagger

    api文档设计工具是用来描述和辅助API开发的. 一.RAML https://raml.org/ https://wenku.baidu.com/view/9523238d5ef7ba0d4b733 ...

  8. .net core 使用 swagger 生成接口文档

    微软参考文档:https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs= ...

  9. Java Web项目中使用Freemarker生成Word文档遇到的问题

    这段时间项目中使用了freemarker生成word文档.在项目中遇到了几个问题,在这里记录一下.首先就是关于遍历遇到的坑.整行整行的遍历是很简单的,只需要在整行的<w:tr></w ...

随机推荐

  1. Incorrect string value: '\xE8\x8B\x8F\xE6\x99\xA8...' for column 'user_name' at row 1

    前端插入数据的时候报如下错误: Incorrect string value: '\xE8\x8B\x8F\xE6\x99\xA8...' for column 'user_name' at row ...

  2. ulimit资源配置

    基本理解 linux对每个用户能使用的系统资源有一定限制.如果没有限制,在多用户登录,并且都消耗大量资源时,对系统产生复杂的影响.ulimit内建一套参数,来规定一个用户能使用多少资源. [root@ ...

  3. DataTable数据检索的性能分析[转]

    原文链接 作者写得非常好,我学到了许多东西,这里只是转载! 我们知道在.NET平台上有很多种数据存储,检索解决方案-ADO.NET Entity Framework,ASP.NET Dynamic D ...

  4. DNS练习之正向解析

    配置正向解析: 主机名:sishen63 主机IP:192.168.1.63 操作系统:Red Hat Enterprise Linux Server release 6.5 (Santiago) 安 ...

  5. CSS3常用属性浏览器兼容前缀

    1.检测网站https://gsnedders.html5.org/outliner/ 2.查询是否支持前缀http://caniuse.com 3.border-radius\box-shadow\ ...

  6. ubuntu 下service php5-fpm restart 报错 stop: Unknown instance: 解决

    问题描述: 在安装完扩展后,重启php-fpm,发现一直停止报错 stop: Unknown instance: 通过查看进程,也查询不到该主进程 解决办法: 干掉现在正在执行的进程 pkill ph ...

  7. 时间插件-daterangepicker

    一款基于bootstrap的时间插件daterangepicker,顾名思义,主要用于时间区间选择,也可做单个时间选择 demo.1汉化版的一个时间选择案例 <!DOCTYPE html> ...

  8. 【HEVC帧间预测论文】P1.9 Coding Tree Depth Estimation for Complexity Reduction of HEVC

    Coding Tree Depth Estimation for Complexity Reduction of HEVC <HEVC标准介绍.HEVC帧间预测论文笔记>系列博客,目录见: ...

  9. web页面调用IOS的事件

    /** * js 调用ios的方法 * @param callback */ function connectWebViewJavascriptBridge(callback) { if (windo ...

  10. Java之流水号生成器实现

    参考:https://www.jianshu.com/p/331b872e9c8f 1.建立一张存放的表 CREATE TABLE `sys_serial_number` ( `id` bigint( ...