基於SpringMVC下的Rest服務框架搭建【1、集成Swagger】
1、需求背景
SpringMVC本身就可以開發出基於rest風格的服務，通過簡單的配置，即可快速開發出一個可供客戶端調用的rest服務，通常這些服務要不就是用於手機app的開發，要不就是提供給第三方開發者使用，不管哪種情況，你都需要提供詳細的說明給別人，而Swagger就是為這種情況而生的，通過在接口上的注解，生成可供第三方模擬測試和閱讀的接口列表，既美觀又使用，真是行走江湖之必備良葯。
【XmPlatform原創，轉載的話請注明】
下面先上美圖：
好了，下面言歸正傳，該如何將Swagger集成到springMVC中呢？
2、依賴包以及Swagger-ui版本
- 如果你用的是maven，依賴包如下：
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-models</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.wordnik</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.3.11</version>
</dependency>
<!-- swagger-springmvc dependencies -->
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>15.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.4.4</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.4.4</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>2.4.4</version>
</dependency>
<dependency>
<groupId>com.fasterxml</groupId>
<artifactId>classmate</artifactId>
<version>1.1.0</version>
</dependency>
- 如果你用的是jeesite框架的話，你只需引入下面三個lib即可：
swagger-annotations-1.3.11.jar
swagger-models-1.0.2.jar
swagger-springmvc-1.0.2.jar
- Swagger-ui版本
大家可以到https://github.com/swagger-api/swagger-ui/releases下載最新的版本，目前最新版本為2.1.4
3、新建配置Java文件
在你的JavaWeb工程中新建一個名為SwaggerConfig的java文件，代碼如下：
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
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.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
/**
* @author xiegx
* @version 創建時間：2016-8-16 下午2:01:10
* SwaggerUI配置
*/
@Configuration
@EnableSwagger
@EnableWebMvc
@ComponentScan(basePackages ={"com.xxx.soa"})
public class SwaggerConfig extends WebMvcConfigurerAdapter {
private SpringSwaggerConfig springSwaggerConfig;
/**
* Required to autowire SpringSwaggerConfig
*/
@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
{
this.springSwaggerConfig = springSwaggerConfig;
}
/**
* Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
* framework - allowing for multiple swagger groups i.e. same code base
* multiple swagger resource listings.
*/
@Bean
public SwaggerSpringMvcPlugin customImplementation()
{
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo())
.includePatterns(".*")
.swaggerGroup("XmPlatform")
.apiVersion("1.0.0");
}
@Override
public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
configurer.enable();
}
/*
* "標題 title",
* "描述 description",
* "termsOfServiceUrl",
* "聯系郵箱 contact email",
* "許可證的類型 license type",
* "許可證的鏈接 license url"
*/
private ApiInfo apiInfo()
{
ApiInfo apiInfo = new ApiInfo(
"xxx平台API文檔",
"后台RESTful API",
"",//
"admin@xmplatform.com",
"",
"");
return apiInfo;
}
}
注意：basePackages為掃描的包路徑(你的controller所在的包路徑)，其他的東西大家看看應該就懂的了，就不多說了。
4、新建測試Controller
例如新建一個TestController.java，代碼如下：
@Controller
@RequestMapping(value = "/soa/test")
@Api(value="TestController",description="測試接口描述")
public class TestController {
/*
* @ApiOperation(value = "接口說明", httpMethod ="接口請求方式", response ="接口返回參數類型", notes ="接口發布說明"
*
* @ApiParam(required = "是否必須參數", name ="參數名稱", value ="參數具體描述"
*/
@RequestMapping(value = {""})
@ApiOperation(value="接口說明(測試)",httpMethod="GET",notes="在沒有會話、沒有簽名的情況下，進入方法體")
public void test(HttpServletRequest request, HttpServletResponse response, Model model) {
try {
response.getWriter().write("ignoreAll");
} catch (IOException e) {
e.printStackTrace();
}
}
}
上述代碼中的幾個注解需要說明一下：
- Api 表明可供Swagger展示的接口類，value表示接口類的描述（Controller類的這個注解可加可不加，加這個注解更多的是為了顯示接口類的描述）
- ApiOperation 表明這個方法供Swagger展示的接口方法，value等含義詳細可看上述代碼中的注釋
- ApiParam 方法中的參數只有加了這個注解，才能顯示中文描述，否則只顯示英文
5、靜態資源文件的配置
將步驟2、中提到的最新版本的Swagger-ui拷貝到你的JavaWeb工程中
假如你用的是jeesite框架，你可以拷貝到static目錄下，例如static\swagger；你也可以拷貝到WEB-INF目錄下，例如WEB-INF\swagger,不過此時你需要在springMVC配置文件中進行靜態文件過濾的處理，例如<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>
6、收工，啟動應用服務器
打開瀏覽器，訪問swagger目錄中的index.html，即可看到美觀的接口文檔呈現在你面前。
You Want More ？Ok，That is it
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中有人提到過，https://github.com/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文檔吧，提供一個地址給大家：http://docs.swagger.io/swagger-core/apidocs/com/wordnik/swagger/annotations/ApiOperation.html
還有更多問題？歡迎留言討論。