Swagger2使用API

　　由於 Spring Boot 能夠快速開發、便捷部署等特性， 通常在使用 Spring Boot構建 Restful 接口應用時考慮到多終端的原因，這些終端會共用很多底層業務邏輯，因此我們會抽象出這樣一層來同時服務於多個移動端或者 Web 前端。對於不同的終端公用一套接口 Api 時對於聯調測試時就需要知道后端提供的接口Api列表文檔，對於服務端開發人員來說就需要編寫接口文檔，描述接口調用地址參數 結果等，這里借助第三方構建工具Swagger2來實現Api文檔生成功能。

• 添加依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

• 配置文件

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("團隊名", "www.my.com", "[e-mail]");
        return new ApiInfoBuilder()
                .title("文檔標題")
                .description("文檔描述")
                .contact(contact)   // 聯系方式
                .version("1.1.0")  // 版本
                .build();
    }
}

• 控制層

@Api(tags = "樣例接口")
@RestController
public class DemoController {


    @ApiOperation(value = "插入demo")
    @PutMapping("putDemo")
    public Map<String,Object> putDemo() {
        System.out.println("執行插入數據");
        Map<String,Object> map = new HashMap<>();
        map.put("code",200);
        map.put("msg","success");
        return map;
    }

    @ApiOperation(value = "查詢demo")
    @ApiImplicitParam(dataType = "integer",defaultValue = "",required = true)
    @GetMapping("/getDemo/{userId}")
    public List<String> getDemo(@PathVariable Integer userId) {
        List<String> list = new ArrayList<>();
        list.add("OK");
        return list;
    }
}

 

　　訪問瀏覽器,輸入http://localhost:8088/swagger-ui.html

 

常用注解解釋說明：

@Api：修飾整個類，描述Controller的作用
@ApiOperation：描述一個類的一個方法，或者說一個接口
@ApiImplicitParams：多個請求參數
@ApiImplicitParam：一個請求參數

@ApiResponses：HTTP響應整體描述
@ApiResponse：HTTP響應其中1個描述
@ApiModel：用對象來接收參數
@ApiModelProperty：用對象接收參數時，描述對象的一個字段
@ApiIgnore：使用該注解忽略這個API