swagger框架

1.1   介紹

　　Swagger是一個簡單又強大的能為你的Restful風格的Api生成文檔工具。在項目中集成這個工具，根據我們自己的配置信息能夠自動為我們生成一個api文檔展示頁，可以在瀏覽器中直接訪問查看項目中的接口信息，同時也可以測試每個api接口。Swagger生成的api文檔是實時更新的，你寫的api接口有任何的改動都會在文檔中及時的表現出來。

1.2  項目環境

Spring提供了一個與Swagger的集成工具包springfox，讓我們的Spring項目能夠更好的與Swagger融合。詳情可訪問springfox托管在Github上的demo內容。地址：http://springfox.github.io/springfox/

 

1.3   Swagger配置步驟

1）  第一步，在項目的公共模塊pom.xml文件下，引用相關的外部依賴包。如下：

<!-- Swagger2 api文檔生成工具依賴包 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.8.5</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.8.5</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>2.8.5</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>log4j-over-slf4j</artifactId>
</dependency>
<!-- end -->

2）  第二步，自定義配置類實現。

 

Swagger會根據這個配置類的具體實現來生成我們相應的api文檔。通過@ComponentScan注解可以指定掃描的包下的RESTful API接口。regex("/api/v1/.*") 可以根據不同ContentPath 版本接口進行分類。可創建多個Docket實例。

 

@Configuration
@EnableWebMvc
@EnableSwagger2
@ComponentScan(basePackages ={"com.coracle.jomoo.rest"})
public class SwaggerConfig {

@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
                .groupName("api")
                .genericModelSubstitutes(DeferredResult.class)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(false)
                .pathMapping("/")
                .select()
                .paths(or(regex("/api/v1/.*")))
                .build()
                .apiInfo(apiInfo());
    }

private ApiInfoapiInfo() {
ApiInfoapiInfo = new ApiInfo("JOMOO INTERFACE API",
"JoMoo Interface's REST API, for system administrator",
"1.0",
"NO terms of service",
"[e-mail]",
"The Apache License, Version 2.0",
"http://www.apache.org/licenses/LICENSE-2.0.html"
);
return apiInfo;
    }
}

 

3. 通過訪問http://localhost:8080/mxm/swagger-ui.html生成在線接口測試地址。

 

 

3）  第三步，API接口注解

　　a.類注解

 

　　b.方法注解

 

@ApiOperation(value = "批文列表查詢接口",
        notes = "批文列表查詢接口",
        position = 0)
@ApiResponses(value = {@ApiResponse(code = 100, message = "批文列表查詢接口異常"),
        @ApiResponse(code = 200, message = "批文列表查詢接口成功")})
@ResponseBody
@RequestMapping(value = "/list", method = RequestMethod.POST)
public CommonDTO<List<TDocLandInfos>> approvalList(@RequestBody TDocLandInfosParam tDocLandInfosParam, HttpServletRequest request, HttpServletResponse response) throws Exception{
    Page page = new Page(request,response);
    try {
        return listDTO;
    }catch (Exception e){
    }
    return listDTO;
}}

springfox默認會將所有的接口都給你生成文檔,不管你有沒有使用注解@ApiOperation這個注解注釋接口方法,並且如果你沒有為你的接口指定訪問方式,他也會為這個接口生成所有訪問方式的文檔, 下面會有結構展示圖.

 

　　c.參數注解

 

@ApiModel(value = "productlistparam")
@JsonSerialize(include = JsonSerialize.Inclusion.NON_NULL)
public class ProductListParamextends CommonParam{

@ApiModelProperty(value = " 產品分類ID", required = false )
private Long categoryId;
@ApiModelProperty(value = "產品分類關鍵字", required = false )
private String keyword;
@ApiModelProperty(value = "產品分類維度", required = false )
private List<String>keys;
@ApiModelProperty(value = "發布時間段", required = false )
private Integer type;

    //get/set.....
}

 

定義好接收參數的實體類，通過@ApiModelProperty注解對每個參數描述，並根據實際參數是否為必填項，最終生成文檔。如下圖：