基於SpringMVC下的Rest服務框架搭建【一、集成Swagger】

時間  2019-11-17 標籤 基於 springmvc rest 服務 框架 搭建 一、集成Swagger

基於SpringMVC下的Rest服務框架搭建【一、集成Swagger】

一、需求背景

SpringMVC自己就能夠開發出基於rest風格的服務，經過簡單的配置，便可快速開發出一個可供客戶端調用的rest服務，一般這些服務要不就是用於手機app的開發，要不就是提供給第三方開發者使用，無論哪一種狀況，你都須要提供詳細的說明給別人，而Swagger就是爲這種狀況而生的，經過在接口上的註解，生成可供第三方模擬測試和閱讀的接口列表，既美觀又使用，真是行走江湖之必備良藥。
【XmPlatform原創，轉載的話請註明】
下面先上美圖：

img

好了，下面言歸正傳，該如何將Swagger集成到springMVC中呢？

二、依賴包以及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.4javascript

三、新建配置Java文件

在你的JavaWeb工程中新建一個名爲SwaggerConfig的java文件，代碼以下：html

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所在的包路徑)，其餘的東西你們看看應該就懂的了，就很少說了。java

四、新建測試Controller

例如新建一個TestController.java，代碼以下：git

@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();
		}
	}
}

上述代碼中的幾個註解須要說明一下：github

  • Api 代表可供Swagger展現的接口類，value表示接口類的描述（Controller類的這個註解可加可不加，加這個註解更多的是爲了顯示接口類的描述）
  • ApiOperation 代表這個方法供Swagger展現的接口方法，value等含義詳細可看上述代碼中的註釋
  • ApiParam 方法中的參數只有加了這個註解，才能顯示中文描述，不然只顯示英文

五、靜態資源文件的配置

將步驟二、中提到的最新版本的Swagger-ui拷貝到你的JavaWeb工程中web

假如你用的是jeesite框架，你能夠拷貝到static目錄下，例如static\swagger；你也能夠拷貝到WEB-INF目錄下，例如WEB-INF\swagger,不過此時你須要在springMVC配置文件中進行靜態文件過濾的處理，例如<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>spring

六、收工，啓動應用服務器

打開瀏覽器，訪問swagger目錄中的index.html，便可看到美觀的接口文檔呈如今你面前。json

img

















You Want More ？Ok，That is it

一、如何漢化/顯示中文api

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> -->

二、在swagger-ui中默認的參數的Content Type是application/json，測試時發現後臺參數沒有接收到值，怎麼辦？

img

你們可能會問，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="在沒有會話、沒有簽名的狀況下，進入方法體")

img

  • 那在什麼狀況下，參數的Content Type纔是application/json呢？

當你的參數加了@RequestBody註解的時候，表示此參數接收的是json數據，這個時候你就能夠將consumes寫爲application/json了

三、想要知道ApiOperation註解中httpMethod等參數都能寫哪些值？

這個看api文檔吧，提供一個地址給你們：http://docs.swagger.io/swagger-core/apidocs/com/wordnik/swagger/annotations/ApiOperation.html

還有更多問題？歡迎留言討論。

联系我们 沪ICP备13005482号-10