Spring MVC中使用Swagger生成API文档和完整项目示例Demo，swagger-server-api（二十）

一：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)
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";
}
}
}

转载于:https://www.cnblogs.com/MaxElephant/p/8145007.html

Spring MVC中使用Swagger生成API文档和完整项目示例Demo，swagger-server-api（二十）相关推荐

实体类接口_spring-boot-route（五）整合Swagger生成接口文档
目前,大多数公司都采用了前后端分离的开发模式,为了解决前后端人员的沟通问题,后端人员在开发接口的时候会选择使用swagger2来生成对应的接口文档,swagger2提供了强大的页面调试功能,这样可以有 ...
[Golang梦工厂]一个小项目带你学会GIN框架、JWT鉴权、swagger生成接口文档，看这一篇就够了
前言哈喽,大家好,我是asong,这是我的第八篇原创文章.听说你们还不会jwt.swagger,所以我带来一个入门级别的小项目.实现用户登陆.修改密码的操作.使用GIN(后台回复Golang梦工厂: ...
java后台处理excel_java后台利用Apache poi 生成excel文档提供前台下载示例
之前在项目中会用到在java在后台把数据填入Word文档的模板来提供前台下载,为了自己能随时查看当时的实现方案及方便他人学习我写了这篇博客,访问量已经是我写的博客里第一了.于是乎我在学会用Java在后 ...
springboot 中文文档_还在用 Swagger生成接口文档？我推荐你试试它
JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具. 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又不得不做的事情,我们都不喜欢写文档,但除非项目前后 ...
还在用Swagger生成接口文档？我推荐你试试它.....
点击上方"方志朋",选择"设为星标" 回复"666"获取新整理的面试文章 JApiDocs是一个无需额外注解.开箱即用的SpringBoot ...
idea swagger生成接口文档_spring boot集成Swagger-UI接口文档
本文介绍如何用spring boot集成Swagger-UI,实现项目在线接口文档一.Swagger-UI简介 Swagger是一个Restful风格接口的文档在线自动生成和测试的框架官网对Swa ...
idea swagger生成接口文档_Spring Boot（九）Swagger2自动生成接口文档和Mock模拟数据...
一.简介在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
Java Web项目中使用Freemarker生成Word文档
Web项目中生成Word文档的操作屡见不鲜,基于Java的解决方案也是很多的,包括使用Jacob.Apache POI.Java2Word.iText等各种方式,其实在从Office 2003开始,就 ...
Java项目中使用Freemarker生成Word文档
Web项目中生成Word文档的操作屡见不鲜,基于Java的解决方案也是很多的,包括使用Jacob.Apache POI.Java2Word.iText等各种方式,其实在从Office 2003开始,就 ...

Spring MVC中使用Swagger生成API文档和完整项目示例Demo，swagger-server-api（二十）

Spring MVC中使用Swagger生成API文档和完整项目示例Demo，swagger-server-api（二十）相关推荐

最新文章

热门文章