Swagger與SpringMVC項目整合

時間 2019-11-17

原文原文鏈接

爲了方便的管理項目中API接口，在網上找了好多關於API接口管理的資料，感受目前最流行的莫過於Swagger了，功能強大，UI界面漂亮，而且支持在線測試等等，因此本人仔細研究了下Swagger的使用，下面就如何將Swagger與我的的SpringMVC項目進行整合作詳細說明：html

最終API管理界面：
java

詳細步驟：web

Step1:項目中引入相關jar包：

?spring

1json

2api

3mvc

4app

5webapp

6post

<code class="language-xml" hljs=""> <properties>

<project.build.sourceencoding>UTF-8</project.build.sourceencoding>

<version.spring>3.2.9.RELEASE</version.spring>

<version.jackson>2.4.4</version.jackson>

</properties>

<dependencies>

....

<dependency>

<groupid>com.mangofactory</groupid>

swagger-springmvc</artifactid>

<version>0.9.5</version>

</dependency>

<dependency>

<groupid>com.fasterxml.jackson.core</groupid>

jackson-annotations</artifactid>

<version>${version.jackson}</version>

</dependency>

<dependency>

<groupid>com.fasterxml.jackson.core</groupid>

jackson-databind</artifactid>

<version>${version.jackson}</version>

</dependency>

<dependency>

<groupid>com.fasterxml.jackson.core</groupid>

jackson-core</artifactid>

<version>${version.jackson}</version>

</dependency>

</dependencies></code>

Step2:添加自定義config文件

<code class="language-java" hljs="">package com.spg.apidoc.common.configer;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

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;

/**

* 項目名稱：apidoc

*

* @description:

* @author Wind-spg

* @create_time：2015年2月10日上午10:27:51

* @version V1.0.0

*

*/

@Configuration

@EnableSwagger

// Loads the spring beans required by the framework

public class MySwaggerConfig

{

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(

.*?);

}

private ApiInfo apiInfo()

{

ApiInfo apiInfo = new ApiInfo(

My Apps API Title,

My Apps API Description,

My Apps API terms of service,

My Apps API Contact Email,

My Apps API Licence Type,

My Apps API License URL);

return apiInfo;

}

}</code>

Step3:將此配置加入到Spring容器中，以下：

1	`<code` `class="language-xml"` `hljs=""><bean` `class="com.spg.apidoc.common.configer.MySwaggerConfig"></bean></code>`

Step4:在代碼中添加相關APIAnnotation，以下：

<code class="language-java" hljs=""> @ResponseBody

@RequestMapping(

value = addUser, method = RequestMethod.POST, produces = application/json; charset=utf-8)

@ApiOperation(value = 添加用戶, httpMethod = POST, response = BaseResultVo.class, notes = add user)

public String addUser(@ApiParam(required = true, name = postData, value = 用戶信息json數據) @RequestParam(

value = postData) String postData, HttpServletRequest request)

{

LOGGER.debug(String.format(at function, %s, postData));

if (null == postData || postData.isEmpty())

{

return super.buildFailedResultInfo(-1, post data is empty!);

}

UserInfo user = JSON.parseObject(postData, UserInfo.class);

int result = userService.addUser(user);

return buildSuccessResultInfo(result);

}</code>

說明：
其中@ApiOperation和@ApiParam爲添加的API相關注解，個參數說明以下：
@ApiOperation(value = 「接口說明」, httpMethod = 「接口請求方式」, response = 「接口返回參數類型」, notes = 「接口發佈說明」；其餘參數可參考源碼；
@ApiParam(required = 「是否必須參數」, name = 「參數名稱」, value = 「參數具體描述」