springboot詳解整合swagger方案
1、Swagger簡介
Swagger 是一個規范和完整的框架,用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。
官網: ( https://swagger.io/ )
主要作用是:
1. 使得前後端分離開發更加方便,有利於團隊協作
2. 接口的文檔在線自動生成,降低後端開發人員編寫接口文檔的負擔
3. 功能測試
Spring已經將Swagger納入自身的標準,建立瞭Spring-swagger項目,現在叫 Springfox。通過在項目中引入Springfox ,即可非常簡單快捷的使用Swagger。
2、整合步驟
項目整體架構如下:
首先構建一個maven項目,添加依賴,我本項目隻是一個子模塊,所以相應的版本都是依賴於父版本的,看不到版本號,swagger使用的是2.9.2版本
<dependencies> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-webmvc</artifactId> </dependency> </dependencies>
創建Swagger配置類SwaggerConfig
package com.swagger.config; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @Configuration @ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true") public class SwaggerConfig implements WebMvcConfigurer { @Bean public Docket buildDocket() { // 要掃描的API(Controller)基礎包 return new Docket(DocumentationType.SWAGGER_2) .apiInfo(buildApiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.swagger.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo buildApiInfo() { Contact contact = new Contact("開發者", "", ""); return new ApiInfoBuilder() .title("測試‐應用API文檔") .description("") .contact(contact) .version("1.0.0") .build(); } /*** 添加靜態資源文件,外部可以直接訪問地址 ** @param registry */ @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry .addResourceHandler("/**") .addResourceLocations("classpath:/static/"); registry .addResourceHandler("swagger‐ui.html") .addResourceLocations("classpath:/META‐INF/resources/"); registry .addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META‐INF/resources/webjars/"); } }
在Controller層創建SwaggerController類方便測試,並添加swagger相應註解
package com.swagger.controller; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @Api(value = "測試平臺 ",tags = "測試平臺") @RestController public class SwaggerController { @ApiOperation("測試") @GetMapping(path = "/hello") public String hello(){ return "hello"; } @ApiOperation("測試2") @ApiImplicitParam(name = "name",value = "姓名",required = true,dataType = "string") @GetMapping("/hi") public String hi(String name){ return "hi : "+name; } }
常用Swagger註解如下:
- @Api:修飾整個類,描述Controller的作用 @ApiOperation:描述一個類的一個方法,或者說一個接口
- @ApiParam:單個參數的描述信息
- @ApiModel:用對象來接收參數
- @ApiModelProperty:用對象接收參數時,描述對象的一個字段
- @ApiResponse:HTTP響應其中1個描述
- @ApiResponses:HTTP響應整體描述
- @ApiIgnore:使用該註解忽略這個API
- @ApiError :發生錯誤返回的信息
- @ApiImplicitParam:一個請求參數
- @ApiImplicitParams:多個請求參數的描述信息
創建啟動類SwaggerApplication
package com.swagger; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import springfox.documentation.swagger2.annotations.EnableSwagger2; @SpringBootApplication @EnableSwagger2 //開啟swagger public class SwaggerApplication { public static void main(String[] args) { SpringApplication.run(SwaggerApplication.class,args); } }
啟動SwaggerApplication ,訪問http://localhost:8080/swagger-ui.html
即可以查看接口文檔瞭……
路漫漫其修遠兮,吾將上下而求索,希望此篇文章對大傢有所幫助……
到此這篇關於springboot詳解整合swagger方案的文章就介紹到這瞭,更多相關springboot swagger內容請搜索WalkonNet以前的文章或繼續瀏覽下面的相關文章希望大傢以後多多支持WalkonNet!
推薦閱讀:
- Spring Boot中如何使用Swagger詳解
- 手把手教你SpringBoot快速集成Swagger的配置過程
- SpringBoot集成Swagger3的實現
- Spring Boot 集成 Swagger2構建 API文檔
- 關於springboot集成swagger及knife4j的增強問題