springboot與swagger2的集成
1、出現的背景
隨着互聯網技術的發展，現在的網站架構基本都由原來的后端渲染變成了：前端渲染、先后端分離的形態，而前端和后端的唯一聯系，變成了API接口；
API文檔變成了前后端開發人員聯系的紐帶，變得越來越重要。包括app開發人員和后端直接的交流都是基於api文檔。
手寫接口文檔
手寫Api文檔的幾個痛點：
- 文檔需要更新的時候，需要再次發送一份給前端，也就是文檔更新交流不及時。
- 接口返回結果不明確
- 不能直接在線測試接口，通常需要使用工具，比如postman
- 接口文檔太多，不好管理
- swagger就是一款讓你更好的書寫API文檔的框架。
2、什么是swagger2
編寫和維護接口文檔是每個程序員的職責，根據Swagger2可以快速幫助我們編寫最新的API接口文檔，再也不用擔心開會前仍忙於整理各種資料了，間接提升了團隊開發的溝通效率。
3、swagger2常用注解：
swagger通過注解表明該接口會生成文檔，包括接口名、請求方法、參數、返回信息的等等。
@Api：修飾整個類，描述Controller的作用
@ApiOperation：描述一個類的一個方法，或者說一個接口
@ApiParam：單個參數描述
@ApiModel：用對象來接收參數
@ApiProperty：用對象接收參數時，描述對象的一個字段
@ApiResponse：HTTP響應其中1個描述
@ApiResponses：HTTP響應整體描述
@ApiIgnore：使用該注解忽略這個API
@ApiError ：發生錯誤返回的信息
@ApiImplicitParam：一個請求參數
@ApiImplicitParams：多個請求參數
@Api：用在請求的類上，表示對類的說明 tags="說明該類的作用，可以在UI界面上看到的注解" value="該參數沒什么意義，在UI界面上也看到，所以不需要配置" @ApiOperation：用在請求的方法上，說明方法的用途、作用 value="說明方法的用途、作用" notes="方法的備注說明" @ApiImplicitParams：用在請求的方法上，表示一組參數說明 @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數的各個方面 name：參數名 value：參數的漢字說明、解釋 required：參數是否必須傳 paramType：參數放在哪個地方 · header --> 請求參數的獲取：@RequestHeader · query --> 請求參數的獲取：@RequestParam · path（用於restful接口）--> 請求參數的獲取：@PathVariable · body（不常用） · form（不常用） dataType：參數類型，默認String，其它值dataType="Integer" defaultValue：參數的默認值 @ApiResponses：用在請求的方法上，表示一組響應 @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息 code：數字，例如400 message：信息，例如"請求參數沒填好" response：拋出異常的類 @ApiModel：用於響應類上，表示一個返回響應數據的信息 （這種一般用在post創建的時候，使用@RequestBody這樣的場景， 請求參數無法使用@ApiImplicitParam注解進行描述的時候） @ApiModelProperty：用在屬性上，描述響應類的屬性
4、SpringBoot 集成 Swagger2
1)、第一步：導入pom
<!-- Swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<!-- END Swagger -->
2)、編寫SwaggerConfig.java配置類
import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("hello")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder()
//頁面標題 .title("Spring Boot中使用Swagger2構建RESTful APIs")
//描述 .description("歡迎來到java思維導圖社區學習") .termsOfServiceUrl("http://www.java-mindmap.com/")
//版本號 .version("1.0") .build(); } }
3)、編寫測試的controller
package com.springboot.example.Controller; import com.springboot.example.Service.StudentService; import com.springboot.example.entity.Student; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiOperation; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RestController; /** * Created by Administrator on 2017/9/13. */ @RestController @RequestMapping("api") @Api("swaggerDemoController相關的api") public class SwaggerDemoController { @Autowired private StudentService studentService; private static final Logger logger= LoggerFactory.getLogger(SwaggerDemoController.class); @ApiOperation(value = "根據id查詢學生信息", notes = "查詢數據庫中某個的學生信息") @ApiImplicitParam(name = "id", value = "學生ID", paramType = "path", required = true, dataType = "Integer") @RequestMapping(value = "/{id}", method = RequestMethod.GET) public Student getStudent(@PathVariable int id) { logger.info("開始查詢某個學生信息"); return studentService.selectStudentById(id); } }
4)、啟動項目 訪問
訪問路徑：http://localhost:8080/swagger-ui.html
5)、查看頁面的效果
至此 SpringBoot 集成 Swagger2 完成！！！！！！