Spring MVC 整合 Swagger

最新推荐文章于 2020-05-27 17:06:07 发布

转载最新推荐文章于 2020-05-27 17:06:07 发布 · 181 阅读

0 ·

CC 4.0 BY-SA版权

原文链接：https://my.oschina.net/discussjava/blog/1800517

文章标签：

#测试 #ui #python

本文介绍如何将Swagger和SwaggerUI集成到系统中实现接口可视化操作，包括版本选择、配置步骤及测试访问方法。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

2019独角兽企业重金招聘Python工程师标准>>>

Swagger

简要说明

将Swagger和Swagger UI集成到系统中，可以实现接口可视化界面操作。

版本号

Swagger UI 2.2.10
高于该版本，可能会出现“No operations defined in spec”错误
下载地址：https://github.com/swagger-api/swagger-ui/tree/v2.2.10

Swagger UI 配置

下载后解压，将dist目录下的文件拷贝到工程中，这里在static目录下新建了一个swagger-2.2.10文件夹。

静态资源映射

这里放置到静态资源加载目录中，在spring配置文件中开发许可路径即可，这里使用的jeesite快速开发平台，已经对static目录做了设置。

<!-- 静态资源映射 -->
    <mvc:resources mapping="/static/**" location="/static/" cache-period="31536000"/>

Pom 配置文件

前3个是swagger的必须jar包，后面几个根据你当前框架中是否使用到了再进行补充。

<!-- Swagger -->  
		<dependency>    
		    <groupId>com.mangofactory</groupId>    
		    <artifactId>swagger-springmvc</artifactId>    
		    <version>1.0.2</version>    
		</dependency> 
		<dependency>  
	    <groupId>com.mangofactory</groupId>  
		    <artifactId>swagger-models</artifactId>  
		    <version>1.0.2</version>  
		</dependency>  
		<dependency>  
		    <groupId>com.wordnik</groupId>  
		    <artifactId>swagger-annotations</artifactId>  
		    <version>1.3.11</version>  
		</dependency>

<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 配置文件

这里需要注意的是，可以通过两种方式进行配置，这里使用的是注解的方式，如果不使用注解的方式配置需要在Spring配置文件中进行声名。

package com.thinkgem.jeesite.common.config;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

@Configuration  
@EnableSwagger  
@EnableWebMvc  
@ComponentScan(basePackages ={"com.thinkgem.jeesite.modules.blog.web"})
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(".*")  
                .swaggerGroup("XmPlatform")  
                .apiVersion("1.0.0");  
    }  
    
    private ApiInfo apiInfo()  
    {  
        ApiInfo apiInfo = new ApiInfo(  
                "springmvc搭建swagger",  
                "spring-API swagger测试",  
                "My Apps API terms of service",  
                "469088624@qq.com",  
                "web app",  
                "My Apps API License URL");  
        return apiInfo;  
    }  
}

这里值得注意的是，以下代码为自动扫描装载位置，多个包用英文逗号分割。

@ComponentScan(basePackages ={"com.thinkgem.jeesite.modules.blog.web","com.thinkgem.jeesite.modules.blog.sys"})

Swagger UI index.html文件配置

修改Swagger下的index.html文件，这里值得注意的是判断表达式else后的url设置。

配置为“项目访问地址”+/api-docs即可
这里因为放在static目录下所以采用js表达式处理了一下

<!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 type="text/javascript">
    $(function () {
      var url = window.location.search.match(/url=([^&]+)/);
      var currentUrl = window.location.href;
      var prefixUrl = "";
      if (currentUrl.indexOf("static") != -1) {
    	  prefixUrl = currentUrl.substr(0,currentUrl.indexOf("static"));
      }
      if (url && url.length > 1) {
        url = decodeURIComponent(url[1]);
      } else {
        url = prefixUrl + "/api-docs";
      }

      hljs.configure({
        highlightSizeThreshold: 5000
      });

      // Pre load translate...
      if(window.SwaggerTranslator) {
        window.SwaggerTranslator.translate();
      }
      window.swaggerUi = new SwaggerUi({
        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();
          }
        },
        onFailure: function(data) {
          log("Unable to Load SwaggerUI");
        },
        docExpansion: "none",
        jsonEditor: false,
        defaultModelRendering: 'schema',
        showRequestHeaders: false,
        showOperationIds: false
      });

      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>&nbsp;</div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</body>
</html>