上一篇《 簡單搭建SpringBoot項目》講了簡單的搭建SpringBoot 項目，而 SpringBoot 和 Swagger-ui 搭配在持續交付的前后端開發中意義重大，Swagger 規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務，對調用方而言非常直觀，接口也可以點擊try it out!按鈕 進行調試，在實際開發中大大增加了開發效率。點擊可了解更多 swagger 相關信息swagger-ui官網
pom.xml中增加：
<!-- Swagger -->
<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.5.0</version>
</dependency>
SwaggerConfig.java：
package com.example.swagger;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.async.DeferredResult;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import static springfox.documentation.builders.PathSelectors.regex;
/**
* Created by shuai on 2017/5/22.
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 可以定義多個組，比如本類中定義把test和demo區分開了
*/
@Bean
public Docket testApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("test")
.genericModelSubstitutes(DeferredResult.class)
// .genericModelSubstitutes(ResponseEntity.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(true)
.pathMapping("/")// base，最終調用接口后會和paths拼接在一起
.select()
.paths((regex("/api/test/.*")))//過濾的接口
.build()
.apiInfo(testApiInfo());
}
@Bean
public Docket demoApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("demo")
.genericModelSubstitutes(DeferredResult.class)
// .genericModelSubstitutes(ResponseEntity.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(false)
.pathMapping("/")
.select()
.paths((regex("/api/demo/.*")))//過濾的接口
.build()
.apiInfo(demoApiInfo());
}
private ApiInfo testApiInfo() {
return new ApiInfoBuilder()
.title("Test 類型 API")//大標題
.description("這是 Test 類型 API 描述")//詳細描述
.version("1.0")//版本
.termsOfServiceUrl("NO terms of service")
.contact(new Contact("shuai", "http://www.lxweimin.com/u/07b9ae164f95", "1119386572@qq.com"))//作者
.license("The Apache License, Version 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.build();
}
private ApiInfo demoApiInfo() {
return new ApiInfoBuilder()
.title("Demo 類型 API")//大標題
.description("這是 Demo 類型 API 描述")//詳細描述
.version("1.0")//版本
.termsOfServiceUrl("NO terms of service")
.contact(new Contact("shuai", "http://www.lxweimin.com/u/07b9ae164f95", "1119386572@qq.com"))//作者
.license("The Apache License, Version 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.build();
}
}
此時啟動 SpringBoot 工程，在瀏覽器輸入 http://localhost:8080/swagger-ui.html 即可看見：
Swagger-ui效果圖
在 SwaggerConfig.java 文件中配置了掃描接口的路徑，只有符合標準的接口才會顯示出來，
常見swagger注解一覽與使用
- 最常用的5個注解
@Api：修飾整個類，描述Controller的作用
@ApiOperation：描述一個類的一個方法，或者說一個接口
@ApiParam：單個參數描述
@ApiModel：用對象來接收參數
@ApiProperty：用對象接收參數時，描述對象的一個字段 - 其它若干
@ApiResponse：HTTP響應其中1個描述
@ApiResponses：HTTP響應整體描述
@ApiIgnore：使用該注解忽略這個API
下面創建符合規范的接口：
TestController.java:
package com.example.controller;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
/**
* Created by shuai on 2017/5/22.
*/
@Controller
@RequestMapping("/api/test")
public class TestController {
@ResponseBody
@RequestMapping(value = "/user", method= RequestMethod.POST, produces= MediaType.APPLICATION_JSON_VALUE)
@ApiOperation(value="獲取user", notes="根據id獲取User的接口")
public String getUser(
@ApiParam(required=true, name="id", value="主鍵id") @RequestParam(name = "id", required=true) String id
){
return "success";
}
}
當對象作為入參時，需要創建一個對象，對象中要用到上面提到的@ApiModel @ApiModelProperty 等注解：
UserVo.java:
package com.example.vo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* Created by shuai on 2017/5/22.
*/
@ApiModel(description = "用戶的對象")
public class UserVo {
@ApiModelProperty("姓名")
private String name;
@ApiModelProperty("年齡")
private Integer age;
@ApiModelProperty("性別")
private String sex;
//
Get And Set Method...()
DemoController.java:
package com.example.controller;
import com.example.vo.UserVo;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;
import java.util.ArrayList;
import java.util.List;
/**
* Created by shuai on 2017/5/21.
*/
@Controller
@RequestMapping(value = "/api/demo")
public class DemoController {
@ResponseBody
@RequestMapping(value = "/getUser", method = RequestMethod.POST)
@ApiOperation(value="測試getUser", notes="getUser詳細說明", response = UserVo.class)
public UserVo getCount(
@ApiParam( required = true, name = "user", value = "入參為User對象") @RequestBody UserVo user
) {
return user;
}
}
這樣一個簡單的 SpringBoot 和Swagger-ui 結合的工程就完成了，下面啟動運行：
啟動后 swagger-ui 的效果圖
github地址：Spring Boot 教程、技術棧、示例代碼
