Swagger 配置

1 pom配置

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>

2 配置启动类

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.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/*
* Restful API 访问路径:
* http://IP:port/{context-path}/swagger-ui.html * eg:http://localhost:8080/swagger-ui.html
*/
@EnableSwagger2
@Configuration
@EnableWebMvc
@ComponentScan(basePackages = "com.jingqbbridge.business.api.web")
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()  // 选择那些路径和api会生成document
.apis(RequestHandlerSelectors.any()) // 对所有api进行监控
.paths(PathSelectors.any())  // 对所有路径进行监控
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("鲸钱包开发者文档")
.termsOfServiceUrl("https://api.jingqb.com/rest")
.contact("鲸钱包团队")
.version("1.0.0")
.build();
}
}

3 root-context.xml文件配置

<!-- 使用 Swagger -->
<bean class="com.jingqbbridge.frame.util.SwaggerConfig" />

4 servlet-context.xml文件配置

<context:component-scan base-package="com.jingqbbridge" />
<!-- 使用 Swagger Restful API文档时，添加此注解 -->
<mvc:default-servlet-handler />

5 web.xml文件配置

<servlet-mapping>
<servlet-name>springMVC</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>

6 sample

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.RestController;

import com.jingqbbridge.business.GlobalConstants;
import com.jingqbbridge.business.annotation.AccessTypeAnnotation;
import com.jingqbbridge.business.model.ExtMerchant;
import com.jingqbbridge.business.util.MessageUtil;
import com.jingqbbridge.business.util.SecurityUtil;
import com.jingqbbridge.frame.base.web.BaseController;

import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import springfox.documentation.annotations.ApiIgnore;

@RestController
public class LoginApiController extends BaseController {

public static final String getPlatTokenParamNote = "{<br>\"id\":\"商户号\",<br>\"key\":\"商户密钥\"<br>}";

/**
* 获取平台token
*
* @author Aaron.Wu
* @date 2016-06-08 09:54:02
*/
@RequestMapping(value = "/api/getPlatToken", method = RequestMethod.POST)
@AccessTypeAnnotation(value = AccessTypeAnnotation.EXTERNAL)
@ApiOperation(value = "获取接口调用凭据", notes = "获取接口调用凭据", tags={ "鲸钱包开发者文档", })
public Map<String, Object> getPlatToken(@ApiParam(required = true, name = "paramMap", value=getPlatTokenParamNote) @RequestBody Map<String, String> paramMap) throws Exception {
Map<String, Object> resultMap = new HashMap<String, Object>();
String id = paramMap.get("id");
String key = paramMap.get("key");
Map<String, ExtMerchant> merchantList = SecurityUtil.getExtMerchantList();
ExtMerchant extMerchant = merchantList.get(id);
String platToken = "";
if (extMerchant != null && key.equals(extMerchant.getKey())) {
platToken = SecurityUtil.getAccessToken(id);
} else {
return MessageUtil.addMsgToResultForExt("E10000", null);
}
resultMap.put("platToken", platToken);
return MessageUtil.addMsgToResultForExt(GlobalConstants.Result.CODE_OK, resultMap);
}

7 国际化-中文显示配置「swagger-ui.html」中添加以下配置

<!-- Some basic translations -->
<script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>

※参考资料↓

swagger注解资料
https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

封装swagger
http://www.sosoapi.com/