SpringMvc 集成构建 Swagger

程序员文章站 2024-03-02 16:56:46

...

Springmvc项目中集成Swagger。

步骤

一，

maven的pom片段：下面的swagger 1 与 swagger 2 的配置都可以，参照一部分就可以，都能跑起来。

————————————————————————————————

<!-- swagger 1 -->

<dependency>
   <groupId>com.mangofactory</groupId>
   <artifactId>swagger-springmvc</artifactId>
   <version>1.0.2</version>
   <!-- swagger-springmvc 依赖spring-web 3.*.*， 与原工程spring-web：4.3.9冲突，排除原来的依赖版本 -->
   <exclusions>
      <exclusion>
         <groupId>org.springframework</groupId>
         <artifactId>spring-web</artifactId>
      </exclusion>
   </exclusions>
</dependency>
<dependency>
   <groupId>com.mangofactory</groupId>
   <artifactId>swagger-models</artifactId>
   <version>1.0.2</version>
   <!-- swagger-springmvc 依赖spring-web 3.*.*， 与原工程spring-web：4.3.9冲突，排除原来的依赖版本 -->
   <exclusions>
      <exclusion>
         <groupId>org.springframework</groupId>
         <artifactId>spring-web</artifactId>
      </exclusion>
   </exclusions>
</dependency>
<dependency>
   <groupId>com.wordnik</groupId>
   <artifactId>swagger-annotations</artifactId>
   <version>1.3.11</version>
   <!-- swagger-springmvc 依赖spring-web 3.*.*， 与原工程spring-web：4.3.9冲突，排除原来的依赖版本 -->
   <exclusions>
      <exclusion>
         <groupId>org.springframework</groupId>
         <artifactId>spring-web</artifactId>
      </exclusion>
   </exclusions>
</dependency>
<!-- swagger-springmvc dependencies -->
<dependency>
   <groupId>com.fasterxml.jackson.core</groupId>
   <artifactId>jackson-core</artifactId>
   <version>2.5.4</version>
</dependency>
<dependency>
   <groupId>com.fasterxml.jackson.core</groupId>
   <artifactId>jackson-annotations</artifactId>
   <version>2.5.4</version>
</dependency>
<dependency>
   <groupId>com.google.guava</groupId>
   <artifactId>guava</artifactId>
   <version>15.0</version>
</dependency>
<dependency>
   <groupId>com.fasterxml</groupId>
   <artifactId>classmate</artifactId>
   <version>1.1.0</version>
</dependency>

<!-- swagger 2 -->

<dependency>
   <groupId>com.mangofactory</groupId>
   <artifactId>swagger-springmvc</artifactId>
   <version>1.0.2</version>
   <!-- swagger-springmvc 依赖spring-web 3.*.*， 与原工程spring-web：4.3.9冲突，排除原来的依赖版本 -->
   <exclusions>
      <exclusion>
         <groupId>org.springframework</groupId>
         <artifactId>spring-web</artifactId>
      </exclusion>
   </exclusions>
</dependency>
<dependency>
   <groupId>com.fasterxml.jackson.core</groupId>
   <artifactId>jackson-core</artifactId>
   <version>2.5.1</version>
</dependency>
<dependency>
   <groupId>com.fasterxml.jackson.core</groupId>
   <artifactId>jackson-databind</artifactId>
   <version>2.5.1</version>
</dependency>
<dependency>
   <groupId>com.fasterxml.jackson.core</groupId>
   <artifactId>jackson-annotations</artifactId>
   <version>2.6.0</version>
</dependency>

————————————————————————————————

二，

springmvc的xml文件中加入以下配置。

1，注册Swagger相关类文件。

<!-- 将 springSwaggerConfig加载到spring容器 -->
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
<!-- 将自定义的swagger配置类加载到spring容器 -->
<bean class="com.zstimes.riskManage.util.controller.SwaggerConfig" />

————————————————————————————————

2，对静态访问的配置，不被springmvc所拦截。

<!-- 对静态资源文件的访问 -->

<mvc:resources mapping="/swagger/**" location="/swagger/" />

————————————————————————————————

三，创建Swagger配置类，SwaggerConfig.java，与容器定义的bean路径（上面二的部分）要保持一致。还有一个测试的Controller类。

SwaggerConfig.java：

package com.zstimes.riskManage.util.controller;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;

/**
 * Created by zzd on 2018/4/15.
 */
public class SwaggerConfig {

    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(
                "Swagger",
                "SpringMvc-API swagger测试",
                "Apps API",
                "RTHD",
                "web app",
                "Apps API License URL");
        return apiInfo;
    }
}

Controller片段：

@Api(value = "user")
@Controller
@RequestMapping("/user")
public class UserController extends AbstractBaseController{
	private static final Logger LOGGER = LogUtil.get();
	

	@Autowired
	private BenQiYeService benQiYeService;

	/**
	 * 
	 * @Title: find 
	 * @Description: 测试
	 * @param req
	 * @return
	 * @return: AjaxResult
	 */
	@RequestMapping(value = "/findPageByCondition",produces = "application/json;charset=UTF-8")
	@ResponseBody
	@ApiOperation(value = "CESI",HhttpMethod="POST",notes="get user by id")

四，与Swagger-UI整合

配置了扫描哪些接口，Swagger会把这些接口生成json格式的文档，json文档直接看很不人性化，所以用这个Swagger-UI把json格式的文档转成页面！

1）Swagger-UI官网git下载版本2.10：

下载地址：https://github.com/swagger-api/swagger-ui/tree/v2.2.10

其他版本没都试过，版本不对会出现以下问题：页面正常显示，但是就不出现接口文档，然后下面是这句话。

No operations defined in spec!

SpringMvc 集成构建 Swagger

下载这里面的dist文件夹，把文件夹整个拷贝到你项目工程的webapp的swagger下，swagger自己创建的，这个目录可以自行定义。
2）找到dist文件夹下的index.html文件，把大概第40行的url改成url = “http://localhost:8080/项目名称/api-docs”;注意这个api-docs是固定的，不要改！

五，启动项目

浏览器输入http://域名:端口/项目名/dist/index.html 就看到效果了,成功！

SpringMvc 集成构建 Swagger