欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

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


SpringMvc 集成构建 Swagger


整合时遇到的问题:

1,因为是集成到现有的项目中,现有的项目的spring-web是4.3.9, 但是Swagger-springmvc依赖是的spring-web3.*.*的jar,所以exclusion排除一下。

2,就是整合Swagger-UI的时候发生版本上面说的问题。 目前用的版本是 v2.2.10