spring mvc和swagger整合

pom.xml 導入jar

jar包	所屬	備注
spring-core	spring	spring核心包
spring-expression	spring	spEl表達式
spring-beans	spring	spring bean
spring-context	spring	spring上下文
spring-context-support	spring	email/scheduler/freemarker支持
spring-orm	spring	orm支持
spring-jdbc	spring	jdbc支持
spring-web	spring	springmvc支持 一般用到監聽器加載applicationconfig.xml
spring-webmvc	spring	spring mvc
spring-data-jpa	spring	ORM框架，依賴於hibernate支持
io.swagger.swagger-core	swagger	swagger核心包
com.fasterxml.classmate	swagger	swagger依賴包
com.google.guava.guava	swagger	swagger依賴包,google公司開發jar包
io.springfox.springfox-swagger2	swagger	swagger依賴包
io.springfox.springfox-swagger-ui	swagger	swagger ui包
com.github.caspar-chen.swagger-ui-layer	swagger	swagger-ui-layer 是替換swagger ui一個包，另外一種展現形式，但是這個包對應服務端響應狀態碼，不是200的話，無法顯示json串，解決辦法：下載源碼，修改源碼打包，然后放到maven的私服中，在下載到本地

配置spring-mvc.xml文件

<mvc:resources mapping="docs.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>
<mvc:default-servlet-handler/>

docs.html: 是映射swagger-ui-layer文件jar里面的/META-INF/resources/這個目錄下docs.html

swagger-ui.html：是映射swagger-ui文件jar里面的/META-INF/resources/這個目錄下docs.html

/webjars/**：映射到swagger-ui文件里面這個/META-INF/resources/webjars/目錄下

注意點：這里用到spring mvc默認的servlet,這個是專門來處理靜態資源的，在spring-mvc配置文件里面增加

mvc:default-servlet-handler，或者在web.xml文件里面配置也行，配置如下：

<servlet-mapping>

<servlet-name>default</servlet-name>

<url-pattern>*.jpg</url-pattern>

</servlet-mapping>

新建SwaggerConfig配置java類文件

@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan(basePackages = {包路徑})
public class SwaggerConfig {
​
    @Bean
    public Docket customDocket() throws IOException, UNAuthorizedCallerException {
        //這里判斷是線上還是線下，這里我用的是枚舉，需要自己寫兩個值 ONLINE(0),OFFLINE(1)，增加  valueOf方法
        if(SwaggerEnvEnum.valueOf(edufeSetting.getEnableSwagger()) == SwaggerEnvEnum.ONLINE) {
            return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfoOnline())
                   .select()
                   .paths(PathSelectors.none())
                   .build();
       }else {
            return new Docket(DocumentationType.SWAGGER_2)
                   .genericModelSubstitutes(DeferredResult.class)
                   .useDefaultResponseMessages(false)
                   .forCodeGeneration(false)
                   .pathMapping("/")
                   .select()
                   .build()
                   .apiInfo(apiInfo());
       }
   }
​
    /**
     * 開發和測試環境使用
     * @return
     */
    private ApiInfo apiInfo() {
​
        Contact contact = new Contact("XX測試接口", "http://www.baidu.com/");
        return new ApiInfoBuilder()
               .contact(contact)
               .title("XX接口")
               .description("接口描述")
               .version("1.0.0")
               .build();
   }
​
    /**
     * 預生成環境使用
     * @return
     */
    private ApiInfo apiInfoOnline() {
        return new ApiInfoBuilder()
               .title("")
               .description("")
               .license("") 
               .licenseUrl("")
               .termsOfServiceUrl("")
               .version("")
               .contact(new Contact("","", ""))
               .build();
   }
}

swagger常用的注解配置

常用注解：

• @Api()用於類； 表示標識這個類是swagger的資源

• @ApiOperation()用於方法； 表示一個http請求的操作

• @ApiParam()用於方法，參數，字段說明； 表示對參數的添加元數據（說明或是否必填等）

• @ApiModel()用於類 表示對類進行說明，用於參數用實體類接收

• @ApiModelProperty()用於方法，字段 表示對model屬性的說明或者數據操作更改

• @ApiIgnore()用於類，方法，方法參數 表示這個方法或者類被忽略

• @ApiImplicitParam() 用於方法 表示單獨的請求參數

• @ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam

• 具體使用舉例說明： @Api() 用於類；表示標識這個類是swagger的資源 tags–表示說明 value–也是說明，可以使用tags替代 但是tags如果有多個值，會生成多個list

• @ApiOperation() 用於方法；表示一個http請求的操作 value用於方法描述 notes用於提示內容 tags可以重新分組（視情況而用） @ApiParam() 用於方法，參數，字段說明；表示對參數的添加元數據（說明或是否必填等） name–參數名 value–參數說明 required–是否必填

• @ApiModel()用於類 ；表示對類進行說明，用於參數用實體類接收 value–表示對象名 description–描述 都可省略

  @ApiModelProperty()用於方法，字段； 表示對model屬性的說明或者數據操作更改 value–字段說明 name–重寫屬性名字 dataType–重寫屬性類型 required–是否必填 example–舉例說明 hidden–隱藏

• @ApiIgnore()用於類或者方法上，可以不被swagger顯示在頁面上 比較簡單, 這里不做舉例

  • @ApiImplicitParam() 用於方法

  • 表示單獨的請求參數

  • @ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam

  • name–參數ming

  • value–參數說明

  • dataType–數據類型

  • paramType–參數類型

  • example–舉例說明

  參考博客：http://blog.csdn.net/u014231523/article/details/76522486