当前位置：首页 > 后端开发 > Spring集成Swagger

Spring集成Swagger

6个月前 (05-25)45

1.1 Swagger 是一个简单、强大的 Restful API 文档生成管理工具.

　　通过 swagger-spring 项目实现了与 Sping MVC 框架的无缝集成功能，方便生成 spring restful 风格的接口文档，在项目中集成这个工具，根据我们自己的配置信息能够自动为我们生成一个 API 文档展示页，可以在浏览器中直接访问查看项目的接口信息（如下图1所示），同时swagger-ui还可以测试spring restful 风格的接口功能，可以对项目提供的每一个 API 接口进行相应的测试。Swagger 生成的 API 文档是实时更新的，API 接口有任何改动都会在文档中及时的表现出来。

1.2 项目环境

　　Spring 提供了一个与 Swagger 的集成工具包 springfox，让 Spring 项目能够更好的与Swagger 融合，官网提供两个版本可完成集成：

　　➢ swagger-springmvc 　　　　➢ springfox-swagger2

　　两种版本配置不同,以最新的springfox-swagger2为例，项目运行环境：

　　➢ JDK1.8（注：必须使用 JDK1.8 否则 swagger2 无法运行）

　　➢ Spring 4.1.7

　　项目中所需 Maven 依赖：

　　　　➢ springfox-swagger2

　　　　➢ springfox-swagger-ui

　　　　➢ guava

　　　　➢ mapstruct-jdk8

　　　　➢ Jackson

　　　　　　 jackson-core

　　　　　　 jackson-databind jackson-annotations

1.3配置步骤

　　1.3.1 在 pom.xml 文件中添加 Swagger2 相关的依赖，配置（部分）如下

<!--SwaggerUI start-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
  <!--SwaggerUI end-->

　　1.3.2 Swagger2 配置类：SwaggerConfig.java（放入到controller包中）

 1 package com.ytzl.itrip.auth.controller;
 2 
 3 import org.springframework.context.annotation.Bean;
 4 import org.springframework.context.annotation.ComponentScan;
 5 import org.springframework.context.annotation.Configuration;
 6 import org.springframework.web.servlet.config.annotation.EnableWebMvc;
 7 import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
 8 import springfox.documentation.builders.ApiInfoBuilder;
 9 import springfox.documentation.builders.PathSelectors;
10 import springfox.documentation.builders.RequestHandlerSelectors;
11 import springfox.documentation.service.ApiInfo;
12 import springfox.documentation.service.Contact;
13 import springfox.documentation.spi.DocumentationType;
14 import springfox.documentation.spring.web.plugins.Docket;
15 import springfox.documentation.swagger2.annotations.EnableSwagger2;
17
20 
21 @EnableSwagger2
22 //@EnableWebMvc
23 @ComponentScan("com.ytzl.itrip.auth.controller")
24 @Configuration //bean
25 public class SwaggerConfig extends WebMvcConfigurationSupport {
26     @Bean
27     public Docket createDocket(){
28         return new Docket(DocumentationType.SWAGGER_2)
29                 .apiInfo(getApiInfo())  //api信息
30                 .select()   //扫描哪个路径下的哪些API
31                 .apis(RequestHandlerSelectors.any())
32                 .paths(PathSelectors.any())
33                 .build();
34     }
35     private  ApiInfo getApiInfo(){
36         return new ApiInfoBuilder()
37                 .title("标题  xxx项目xxx模块")
38                 .contact(new Contact("name","","联系方式"))
39                 .version("1.1")
40                 .build();
41     }
42 
43 }

　　　　1> @ComponentScan(basePackages = {"cn.itrip.controller"})：设置 Swagger 扫描包：

　　　　2> @EnableSwagger2：使 Swagger2 生效

　　　　3> @Configuration：自动在本类上下文加载一些环境变量信息

　　　　4> 创建Docker对象

　　　　　　* Docker apiInfo()：用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息） *

　　　　　　* ApiSelectorBuilder select()：设置哪些接口暴露给Swagger展示

　　　　　　* ApiSelectorBuilder apis()：要展示的API apis()

　　　　　　　　** RequestHandlerSelectors.any() 任何路径

　　　　　　　　** RequestHandlerSelectors.basePackage("com.ustcinfo.*") 包位置

　　　　　　　　* *RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class) 类位置

　　　　　　 * ApiSelectorBuilder paths()：要展示的路径

　　　　　　　　* *PathSelectors.any()：任何路径都可以

　　　　　　* Docker build()：创建Docker对象

　　　　5>配置 ApiInfoBuilder（界面显示）自定义该API工具展示信息，标题、描述、更新的地址、作者信息、版本等 *

　　　　　　* ApiInfoBuilder title(String str): 设置标题

　　　　　　* ApiInfoBuilder description(String str): 描述

　　　　　　* ApiInfoBuilder termsOfServiceUrl(String str): 更新地址

　　　　　　* ApiInfoBuilder contact(String str): 作者信息

　　　　　　* ApiInfoBuilder version(String str): 版本

　　1.3.3 Spring MVC 配置文件　　

　　　　1> <mvc:default-servlet-handler />：配置对静态文件的处理方式

<!-- 使用 Swagger Restful API 文档时，添加此注解 --> 
<mvc:default-servlet-handler />

　　　　2> <context:component-scan/>：添加指定扫描(一般情况下不用另写)

<context:component-scan base-package="cn.itrip.controller"> 
    <context:include-filter type="annotation" expression="org.springframework.stereotype.Controller"/> 
    <context:include-filter type="annotation" expression="org.springframework.context.annotation.Configuration"/> 
    <context:include-filter type="annotation" expression="org.springframework.scheduling.annotation.Scheduled"/> 
</context:component-scan>

到此准备工作已完成，可以使用了

@Controller
@RequestMapping("/api")
@Api(description = "用户模块")
public class ItripUserController {

    @ApiOperation(value = "用户名的验证",httpMethod = "GET",produces = "application/json",response = Dto.class,notes = "验证用户名是否存在")
    @RequestMapping(value="/ckusr",method = RequestMethod.GET,produces = "application/json")
    @ResponseBody
    public Dto ckusr(@RequestParam("name")
                       @ApiParam(value="用户账号",required=true) String name){
}