springmvc使用swagger生成rest api文档

pom.xml

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

ApiConfig.java

package com.geostar.gfstack.operationcenter.core.common.util;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration //必须存在
@EnableSwagger2 //必须存在
@EnableWebMvc //必须存在
public class ApiConfig {

@Bean
public Docket customDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(GeoRequestHandlerSelectors.basePackage("com.geostar.gfstack.operationcenter.cloudform.action"))
.paths(PathSelectors.any())
.build()
.useDefaultResponseMessages(false);
}

private ApiInfo apiInfo() {
Contact contact = new Contact("武大吉奥", "http://www.geostar.com.cn/", "techsupport@geostar.com.cn");
return new ApiInfo("综合运维管理系统API接口",//大标题 title
"综合运维管理系统API接口",//小标题
"1.8.2.0",//版本
"http://www.geostar.com.cn/",//termsOfServiceUrl
contact,//作者
"武大吉奥",//链接显示文字
"http://www.geostar.com.cn/"//网站链接
);
}

}

确保ApiConfig在spring扫描范围内

GeoRequestHandlerSelectors.java

package com.geostar.gfstack.operationcenter.core.common.util;

import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
import org.springframework.core.annotation.AnnotationUtils;
import springfox.documentation.RequestHandler;

import java.lang.annotation.Annotation;

public class GeoRequestHandlerSelectors {
private GeoRequestHandlerSelectors() {
throw new UnsupportedOperationException();
}

/**
* Any RequestHandler satisfies this condition
*
* @return predicate that is always true
*/
public static Predicate<RequestHandler> any() {
return Predicates.alwaysTrue();
}

/**
* No RequestHandler satisfies this condition
*
* @return predicate that is always false
*/
public static Predicate<RequestHandler> none() {
return Predicates.alwaysFalse();
}

/**
* Predicate that matches RequestHandler with handlers methods annotated with given annotation
*
* @param annotation - annotation to check
* @return this
*/
public static Predicate<RequestHandler> withMethodAnnotation(final Class<? extends Annotation> annotation) {
return new Predicate<RequestHandler>() {
@Override
public boolean apply(RequestHandler input) {
return null != AnnotationUtils.findAnnotation(input.getHandlerMethod().getMethod(), annotation);
}
};
}

/**
* Predicate that matches RequestHandler with given annotation on the declaring class of the handler method
*
* @param annotation - annotation to check
* @return this
*/
public static Predicate<RequestHandler> withClassAnnotation(final Class<? extends Annotation> annotation) {
return new Predicate<RequestHandler>() {
@Override
public boolean apply(RequestHandler input) {
return declaringClass(input).isAnnotationPresent(annotation);
}
};
}

/**
* Predicate that matches RequestHandler with given base package name for the class of the handler method.
* This predicate includes all request handlers matching the provided basePackage
*
* @param basePackage - base package of the classes
* @return this
*/
public static Predicate<RequestHandler> basePackage(final String... basePackage) {
return new Predicate<RequestHandler>() {
@Override
public boolean apply(RequestHandler input) {
String name = declaringClass(input).getPackage().getName();
for (String _package : basePackage) {
if (name.startsWith(_package)) {
return true;
}
}
return false;
}
};
}

private static Class<?> declaringClass(RequestHandler input) {
return input.getHandlerMethod().getMethod().getDeclaringClass();
}
}

下载前端资源文件

https://github.com/swagger-api/swagger-ui/archive/v2.2.10.zip

备用地址：https://files.cnblogs.com/files/nihaorz/swagger-ui-2.2.10.zip

解压zip文件，拷贝dist到WebRoot下重命名为api，修改api目录下的index.html为如下内容

<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta http-equiv="x-ua-compatible" content="IE=edge">
<title>Swagger UI</title>
<link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32"/>
<link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16"/>
<link href='css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='css/reset.css' media='print' rel='stylesheet' type='text/css'/>
<link href='css/print.css' media='print' rel='stylesheet' type='text/css'/>

<script src='lib/object-assign-pollyfill.js' type='text/javascript'></script>
<script src='lib/jquery-1.8.0.min.js' type='text/javascript'></script>
<script src='lib/jquery.slideto.min.js' type='text/javascript'></script>
<script src='lib/jquery.wiggle.min.js' type='text/javascript'></script>
<script src='lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
<script src='lib/handlebars-4.0.5.js' type='text/javascript'></script>
<script src='lib/lodash.min.js' type='text/javascript'></script>
<script src='lib/backbone-min.js' type='text/javascript'></script>
<script src='swagger-ui.js' type='text/javascript'></script>
<script src='lib/highlight.9.1.0.pack.js' type='text/javascript'></script>
<script src='lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>
<script src='lib/jsoneditor.min.js' type='text/javascript'></script>
<script src='lib/marked.js' type='text/javascript'></script>
<script src='lib/swagger-oauth.js' type='text/javascript'></script>

<!-- 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> -->
<script src='lang/translator.js' type='text/javascript'></script>
<script src='lang/zh-cn.js' type='text/javascript'></script>

<script type="text/javascript">

function getRootPath() {
//获取当前网址，如： http://localhost:8083/uimcardprj/share/meun.jsp var curWwwPath = window.document.location.href;
//获取主机地址之后的目录，如： uimcardprj/share/meun.jsp
var pathName = window.document.location.pathname;
var pos = curWwwPath.indexOf(pathName);
//获取主机地址，如： http://localhost:8083 var localhostPaht = curWwwPath.substring(0, pos);
//获取带"/"的项目名，如：/uimcardprj
var projectName = pathName.substring(0, pathName.substr(1).indexOf('/') + 1);
return (localhostPaht + projectName);
}

function extend(obj) {
var flag = $(obj).data("flag");
if (flag == undefined) {
flag = true;
}
if (flag) {
swaggerUi.collapseAll();
$(obj).html("恢复默认");
} else {
swaggerUi.load()
}
$(obj).data("flag", !flag)
}

$(function () {

$("#logo").attr("href", getRootPath() + "/api");

var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
url = getRootPath() + "/v2/api-docs";
}

hljs.configure({
highlightSizeThreshold: 5000
});

// Pre load translate...
if (window.SwaggerTranslator) {
window.SwaggerTranslator.translate();
}
window.swaggerUi = new SwaggerUi({
apisSorter: "alpha", // can also be a function
operationsSorter: "alpha", // can also be 'alpha' or a function
url: url,
dom_id: "swagger-ui-container",
supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
onComplete: function (swaggerApi, swaggerUi) {
if (typeof initOAuth == "function") {
initOAuth({
clientId: "your-client-id",
clientSecret: "your-client-secret-if-required",
realm: "your-realms",
appName: "your-app-name",
scopeSeparator: " ",
additionalQueryStringParams: {}
});
}

if (window.SwaggerTranslator) {
window.SwaggerTranslator.translate();
}
$("#api_info .info_license").after("<div style='text-align:right;'><a target='_self' href='javascript:;' onclick='extend(this);'>全部折叠</a></div>");
},
onFailure: function (data) {
log("Unable to Load SwaggerUI");
},
docExpansion: "list",
jsonEditor: false,
defaultModelRendering: 'schema',
showRequestHeaders: false,
showOperationIds: false,
validatorUrl: null
});

window.swaggerUi.load();

function log() {
if ('console' in window) {
console.log.apply(console, arguments);
}
}
});
</script>
</head>

<body class="swagger-section">
<div id='header'>
<div class="swagger-ui-wrap">
<a id="logo" href="http://swagger.io"><img class="logo__img" alt="swagger" height="30" width="30"
src="images/logo_small.png"/><span class="logo__title">swagger</span></a>
<form id='api_selector'>
<div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl"
type="text"/></div>
<div id='auth_container'></div>
<div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div>
</form>
</div>
</div>

<div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</body>
</html>

部署项目即可开始使用swagger

参照：

https://github.com/swagger-api/swagger-ui/tree/v2.2.10

https://springfox.github.io/springfox/docs/current/