spring集成swagger

　　隨着互聯網技術的發展，如今的網站架構基本都由原來的後端渲染，變成了：前端渲染、先後端分離的形態，並且前端技術和後端技術在各自的道路上越走越遠。 
前端和後端的惟一聯繫，變成了API接口；API文檔變成了先後端開發人員聯繫的紐帶，變得愈來愈重要，swagger就是一款讓咱們更好地書寫API文檔的框架。swagger能夠用來顯示API文檔。

　　咱們在基於spring框架進行java開發時，當須要使用swagger生成API文檔時，須要先添加swagger的jar包依賴。咱們以在maven項目管理工具中開發項目爲例，在pom.xml中添加以下依賴：

<dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-springmvc</artifactId>
            <version>0.9.5</version>
        </dependency>

        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.7</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.7</version>
        </dependency>
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>19.0</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml</groupId>
            <artifactId>classmate</artifactId>
            <version>1.3.1</version>
        </dependency>

　　接着，要寫一個swagger的核心配置類，以下所示：

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;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

@Configuration//聲明此類是一個swagger的核心配置類
@EnableSwagger//啓用Swagger
@EnableWebMvc//啓用SpringMVC

public class SwaggerConfig {

    //給SpringSwaggerConfig進行賦值
    private SpringSwaggerConfig springSwaggerConfig;

    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }

    /**
     * 自定義實現 customImplementation
     * @return
     */
    @Bean  //再配置一個SwaggerSpringMvcPlugin 的bean，未來SpringMVC生成文檔時要用
    public SwaggerSpringMvcPlugin customImplementation(){
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo())
                .includePatterns(".*?");
    }

    /**
     * title;
      description;
      terms of serviceUrl;
      contact email;
      license type;
      license url;
     * @return
     */
    private ApiInfo apiInfo(){
        ApiInfo apiInfo = new ApiInfo(
                "XXX項目接口文檔",
                "企業版,爲企業用車提供一站式解決方案:海量優質車型,實時調度,會議、商務用車盡享便捷;多種靈活用車方式,快車、專車、接送機一鍵完成",
                "http://192.168.1.236",
                "聯繫郵箱",
                "許可證的類型",
                "許可證的連接"
        );

        return apiInfo;
    }
}

　　而後，在springmvc-config.xml配置文件裏的掃描註解里加上@Configuration，以下所示：

<?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"
       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">

    <!--springmvc 只管掃描 controller包-->
    <context:component-scan base-package="com.itszt.XXX.controller,com.itszt.XXX.controller.swagger">
        <context:include-filter type="annotation" expression="org.springframework.context.annotation.Configuration"/>
    </context:component-scan>

    <!--支持註解->
    <mvc:annotation-driven>
        <!--讓咱們的Adapter有json 轉換能力-->
        <mvc:message-converters>
            <ref bean="jsonconverter"></ref>
        </mvc:message-converters>
    </mvc:annotation-driven>

    <!--jackson給咱們提供的一個json轉換器-->
    <bean id="jsonconverter" class="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter"></bean>

    <bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
        <property name="prefix" value="/WEB-INF/"></property>
        <property name="suffix" value=".jsp"></property>
    </bean>

    <!--靜態資源的處理-->
    <mvc:resources mapping="/pages/*" location="/htmls/"></mvc:resources>
    <mvc:resources mapping="/swagger/**/*" location="/swagger/"></mvc:resources>

    <bean class="com.itszt.XXX.controller.swagger.SwaggerConfig"></bean>
    <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig"></bean>

</beans>

　　接下來,下載swagger- UI，添加到 SpringMVC 的靜態文件的目錄裏。

　　而後，在使用中，實體類上用註解@ApiModel(description = "返回的結果")，其下屬性用註解@ApiModelProperty(notes = "註冊失敗的錯誤信息")；

　　控制器上用註解@Api(description="用戶中心模塊",value = "用戶相關操做")，其下方法用註解@ApiOperation(notes = "驗證用戶接口",value = "用戶登陸使用的方
法",httpMethod = "GET")，方法的參數前用註解@ApiParam(name="username",required = true,value = "用戶名")。

　　最後，咱們在瀏覽器地址欄裏訪問  http://localhost/api-docs，便可看到頁面swagger包下的index.html動態顯示的相應內容：

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <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=([^&]+)/);
      if (url && url.length > 1) {
        url = decodeURIComponent(url[1]);
      } else {
//        url = "http://petstore.swagger.io/v2/swagger.json";
          url = "http://localhost/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
      });

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