准备工作
创建一个Maven web工程
maven web project
下载swagger-ui包
- GitHub repository的Swagger UI工程(当前版本3.16)
-
克隆或者下载该工程
- 到Swagger UI工程文件夹下，打开dist文件夹
dist文件夹位置 -
找到index.html
dist文件夹内容 - 打开index.html并修改URL
修改77行(当前版本在77行)
url: "http://localhost:8686/Jiftown/v2/api-docs", //其中http://localhost:8686/Jiftown为你的工程地址
修改后
集成swagger
copy dist文件目录下文件到webapp下swagger
工程结构图
仅个人习惯
web.xml
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
version="3.1">
<display-name>Archetype Created Web Application</display-name>
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<!-- 设置Spring容器加载配置文件路径 -->
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>classpath:conf/spring/applicationContext-*.xml</param-value>
</context-param>
<!-- Spring view分发器 -->
<servlet>
<servlet-name>DataServer</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<init-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/dispatcher-servlet.xml</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>DataServer</servlet-name>
<url-pattern>/</url-pattern>
<!--拦截/*，这是一个错误的方式，请求可以走到Action中，但转到jsp时再次被拦截，不能访问到jsp。
拦截/，restful风格 弊端：会导致静态文件（jpg,js,css）被拦截后不能正常显示。解决办法看dispatcher-->
</servlet-mapping>
<filter>
<description>字符集过滤器</description>
<filter-name>encodingFilter</filter-name>
<filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
<init-param>
<description>字符集编码</description>
<param-name>encoding</param-name>
<param-value>UTF-8</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>encodingFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
</web-app>
dispatcher-servlet.xml
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:mvc="http://www.springframework.org/schema/mvc" xmlns:aop="http://www.springframework.org/schema/aop"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd
http://www.springframework.org/schema/mvc
http://www.springframework.org/schema/mvc/spring-mvc.xsd http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop.xsd">
<!--启用spring的一些annotation -->
<mvc:annotation-driven/>
<aop:aspectj-autoproxy proxy-target-class="true"/>
<!-- 自动扫描该包，使SpringMVC认为包下用了@controller注解的类是控制器 -->
<context:component-scan base-package="com.jiftown.*"/>
<!-- 解决restful风格的弊端：会导致静态文件（jpg,js,css）被拦截后不能正常显示-->
<mvc:default-servlet-handler/>
</beans>
pom.xml
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.jiftown</groupId>
<artifactId>jiftown-main</artifactId>
<packaging>war</packaging>
<version>1.0-SNAPSHOT</version>
<name>jiftown-main Maven Webapp</name>
<url>http://maven.apache.org</url>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>
<!--swagger依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<!--spring 依赖-->
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-webmvc</artifactId>
<version>4.3.9.RELEASE</version>
</dependency>
<!-- j2ee 相关包-->
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>3.1.0</version>
</dependency>
</dependencies>
<build>
<finalName>jiftown-main</finalName>
</build>
</project>
SwaggerConfiguration.class
@EnableWebMvc
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("标题")
.description("描述")
.license("Apache 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.termsOfServiceUrl("")
.version("1.0.0")
.contact(new Contact("", "", "miaorf@outlook.com"))
.build();
}
}
测试Swagger HelloWorldController.class
@Api(value = "HelloWorld",description = "HelloWorld")
@Controller()
@Scope("prototype")
public class HelloWorldController {
@ApiOperation(value = "开放接口", httpMethod = "GET")
@RequestMapping(value = "/sayHello", method = RequestMethod.GET)
@ResponseBody
public String sayHello(@RequestParam("key")String keyword, HttpServletRequest request, HttpServletResponse response) {
System.out.println(keyword);
return keyword;
}
}
显示结果
页面效果
