1. 程式人生 > >Swagger 與 SpringMVC 整合的步驟

Swagger 與 SpringMVC 整合的步驟

1、新增 Swagger 與 SpringMVC 的依賴

<dependency>
    <groupId>com.mangofactory</groupId>
    <artifactId>swagger-springmvc</artifactId>
    <version>1.0.2</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId> <version>${jackson.version}</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>${jackson.version}</version
>
</dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-annotations</artifactId> <version>${jackson.version}</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>

2、編寫 Swagger 與 SpringMVC 整合的配置類

package com.english17.config;

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;

/**
 * Created by Liwei on 2016/2/14.
 */
@Configuration
@EnableSwagger
public class SwaggerConfig {


    private SpringSwaggerConfig springSwaggerConfig;

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

    /**
     * 自定義實現 customImplementation
     * @return
     */
    @Bean
    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(
                "標題 title",
                "描述 description",
                "termsOfServiceUrl",
                "聯絡郵箱 contact email",
                "許可證的型別 license type",
                "許可證的連結 license url"
        );
        return apiInfo;
    }
}

3、修改配置檔案

(1)在 SpringMVC 的配置檔案中新增和修改:

在 SpringMVC 的掃描註解裡面加上掃描註解 @Configuration

<context:include-filter type="annotation" expression="org.springframework.context.annotation.Configuration"/>

這是因為,我們下面的兩個 bean 都被 @Configuration 註解

<bean class="com.english17.config.SwaggerConfig"></bean>
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig"></bean>

對稱地,要在 Spring 的配置檔案中減去對 @Configuration 的掃描

<context:exclude-filter type="annotation" expression="org.springframework.context.annotation.Configuration"/>

4、下載 UI,複製到 SpringMVC 的靜態檔案的目錄

啟動服務,輸入下面的連結(主機名和埠號要用你自己的)

http://localhost:8888/api-docs

要看到返回一個 json。

http://localhost:8888/resources/swagger/index.html

開發中使用頻率比較高的註解:
1、@ApiModel:標註在類上
2、@ApiModelProperty:標註在屬性上
3、@ApiOperation:標註在方法上
4、@ApiParam:標註在方法引數上
5、@Api:標註在控制器上

具體的使用方法可以直接看原始碼。