springmvc集成swagger实现接⼝⽂档⾃动化⽣成
⼀直苦于⽂档整理⼯作，因为这是⼀个很⽆聊的⼯作，偶然在⽹上看到了swagger这东西，感觉不错，于是动⼿集成了⼀下，眼前⼀亮
Swagger 是⼀个规范和完整的框架，⽤于⽣成、描述、调⽤和可视化 RESTful 风格的 Web 服务。总体⽬标是使客户端和⽂件系统作为服务器以同样的速度来更新。⽂件的⽅法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使⽤功能强⼤的API从未如此简单。
费话少说，下⾯来看⼀下集成的过程，我⽤的环境是：jdk1.8+tomcat7.0+springmvc4.2+maven3.0
1.⾸先，通过maven将相关的jar引⼊项⽬
<!-- swagger -->
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.dataformat</groupId>
<artifactId>jackson-dataformat-xml</artifactId>
<version>2.7.4</version>
</dependency>
<dependency>
<groupId>com.</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.7.4</version>
</dependency>
<dependency>
<groupId>com.</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.7.4</version>
</dependency>
<dependency>
<groupId>com.</groupId>
<artifactId>jackson-core</artifactId>
<version>2.7.4</version>
</dependency>
<!-- swagger -->
2.写⼀个⾃定义的swagger的config类
import org.springframework.beans.factory.annotation.Autowired;
import t.annotation.Bean;
import t.annotation.ComponentScan;
import t.annotation.Configuration;
import org.springframework.fig.annotation.EnableWebMvc;
import com.figuration.SpringSwaggerConfig;
import com.dels.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
/
**
* <B>⽂件名称：</B>SwaggerConfig.java<BR>
* <B>⽂件描述：</B><BR>
*
* <B>版权声明：</B>(C)2014-2015<BR>
* <B>公司部门：</B><BR>
* <B>创建时间：</B>2016年6⽉30⽇<BR>
*
* @author
* @version
*/
springmvc的注解有哪些
@Configuration
@EnableWebMvc
@EnableSwagger
@ComponentScan("Vouchers")
public class SwaggerConfig {
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(".*")
.apiVersion("0.0.1");
/
/.swaggerGroup(PROJECT_NAME);
}
private ApiInfo apiInfo() {
ApiInfo apiInfo = new ApiInfo("My Apps API Title", "My Apps APIDescription", "My Apps API terms ofservice",
"My Apps API ContactEmail", "My Apps API LicenceType", "My Apps API LicenseURL");
return apiInfo;
}
}
3.将这个类交给spring来进⾏管理
<bean class="Vouchers.swagger.SwaggerConfig"/>
4.通过注解的⽅式，让swagger能够知道我们接⼝对应的功能说明
@Controller
@RequestMapping(value = "/user")
@Api(value = "user")
public class UserController {
/**
* 根据⽤户名获取⽤户对象
* @param name
* @return
*/
@RequestMapping(value="/name/{name}", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "根据⽤户名获取⽤户对象", httpMethod = "GET", response = ApiResult.class, notes = "根据⽤户名获取⽤户对象")
public ApiResult getUserByName(@ApiParam(required = true, name = "name", value = "⽤户名") @PathVariable String name) throws Exception{
UcUser ucUser = UserByName(name);
if(ucUser != null) {
ApiResult<UcUser> result = new ApiResult<UcUser>();
result.setCode(Code());
result.setData(ucUser);
return result;
} else {
throw new BusinessException("根据{name=" + name + "}获取不到UcUser对象");
}
}
}
说明：@API(value="user")这个是⽤来分组的，（不过貌似不写也可以，会⾃动根据controller来进⾏分组），@ApiOperation注解对这个⽅法进⾏了说明，@ApiParam注解对⽅法参数进⾏了说明。
4.Swagger-UI配置
Swagger扫描解析得到的是⼀个json⽂档，对于⽤户不太友好。下⾯介绍swagger-ui，它能够友好的展⽰解析得到的接⼝说明内容。
  从github/swagger-api/swagger-ui 获取其所有的 dist ⽬录下东西放到需要集成的项⽬⾥，本⽂放⼊ src/main/webapp/api/ ⽬录下(也可以放到其它⽬录下)。
  修改index.html⽂件，默认是从连接petstore.swagger.io/v2/swagger.json获取 API 的 JSON，这⾥需要将url值修改为{ip}: {port}/{projectName}/api-docs的形式，{}中的值根据⾃⾝情况填写。⽐如我的url值为：localhost:8080/vouchers/api-docs 这⾥最好新建⼀个src/main/webapp/api-do
cs/⽬录，⽤于程序⽣成接⼝对就的json⽂件，我看⽹上的⼈都没有⼿动建，但是我的没有⾃动⽣成，如果你们⾃动⽣成了，可以跳过这⼀步。
  因为swagger-ui项⽬都是静态资源，restful形式的拦截⽅法会将静态资源进⾏拦截处理，所以在springmvc配置⽂件中需要配置对静态⽂件的处理⽅式（我这⾥对⽬录下所有⽂件全部放⾏了）。
<mvc:resources mapping="/api/**" location="/api/" />
OK！⼤功告成，打开浏览器直接访问swagger⽬录下的index.html⽂件，即可看到接⼝⽂档说明了。注意访问地址哦！我的访问地址是：
localhost:8080/vouchers/api/，注意，如果你l没有配置默认欢迎页⾯，你要加index.html访问。
项⽬中遇到了如下问题，参考了wwwblogs/xmplatform/p/5785065.html
1、如何/显⽰中⽂
swagger-ui本⾝是⽀持多语⾔的，在index.html中有这么⼀段代码：
<!-- Some basic translations -->
<!-- <script src='lang/translator.js' type='text/javascript'></script> -->
<!-- <script src='lang/ru.js' type='text/javascript'></script> -->
<!-- <script src='lang/en.js' type='text/javascript'></script> -->
⼤家只需要把注释打开，同时加⼊对应的中⽂js即可，最终修改如下：
<!-- Some basic translations -->
<script src='lang/translator.js' type='text/javascript'></script>
<script src='lang/zh-cn.js' type='text/javascript'></script>
<!-- <script src='lang/en.js' type='text/javascript'></script> -->
2、在swagger-ui中默认的参数的Content Type是application/json，测试时发现后台参数没有接收到值，怎么办？
⼤家可能会问，Content Type是application/json有什么影响，为什么要修改为其他呢？这⾥就要涉及到springMVC中将请求传递过来的参数注⼊到Controller⽅法对应对象的原理了，具体知识⼤家可以搜索⼀下，这个不是本⽂重点我就不多讲了，其实我们通常写的Controller⽅法，默认的Content Type其实是application/x-www-form-urlencoded，⽽swagger中参数的默认Content Type是application/json，这样就会导致使⽤swagger测试时，提交到Controller⽅法的对应参数⽆法正确注⼊。
那么，该如何处理呢，能改成其他吗？
其实在swagger-ui的Issues中有⼈提到过，github/swagger-api/swagger-ui/issues/658，解决的办法就是要设置consumes这个东东。
解决办法到了，那consumes在哪⾥设置呢？
答案就是在@ApiOperation这个注解⾥⾯进⾏设置，将consumes修改为“application/x-www-form-urlencoded”即可，例如：
@ApiOperation(value="接⼝说明(测试)",httpMethod="GET",consumes="application/x-www-form-urlencoded",notes="在没有会话、没有签名的情况下，进⼊⽅法体")
那在什么情况下，参数的Content Type才是application/json呢？
当你的参数加了@RequestBody注解的时候，表⽰此参数接收的是json数据，这个时候你就可以将consumes写为application/json了
3、想要知道ApiOperation注解中httpMethod等参数都能写哪些值？
这个看api⽂档吧，提供⼀个地址给⼤家：docs.swagger.io/swagger-core/apidocs/com/wordnik/swagger/annotations/ApiOperation.html

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。