項目開發實現前后端分離，Swagger2是非常好用使用的一個框架！！！真香警告，個人感覺比Postman開發效率提升了很多，注解項會讓代碼更容易讀
在后端開發中經常需要對移動客戶端提供RESTful API接口，在后期版本快速迭代的過程中，修改接口實現的時候都必須同步修改接口文檔，而文檔與代碼又處於兩個不同的媒介，除非有嚴格的管理機制，不然很容易導致寫出的代碼與接口文檔不一致現象。
為了前后台更好的對接,為了以后交接方便,為了不再長篇大論的手寫api文檔,那么就來用Swagger吧(不是打廣告),它可以輕松的整合到Spring中,它既可以減少我們手寫api文檔的時間，同時又將說明文檔整合到我們的代碼中,這樣前台看着也方便,后台工作也舒坦,
Swagger 是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單(其他好處網上自己搜在這里就不再多說了)。
Swagger也提供了強大的頁面測試功能來調試每個寫好的接口：
1.開發環境
- SpringBoot 2.0.4.RELEASE
- Swagger 2.6.1
- JDK 1.8
2.maven依賴
<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>
3.Swagger2配置類（以下屬於較為基本的屬性配置，后期繼續增加）
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;
@Configuration
public class Swagger2Config {
@Bean
public Docket createDocket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.select().apis(RequestHandlerSelectors.basePackage("com.iflytek.studyproject.controller"))
.paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder().title("Spring boot整合Swagger2學習")
.description("ApiInfo的描述")
.termsOfServiceUrl("no term url")
.version("1.0")
.build();
}
}@Configuration會被項目啟動加載為配置類,等同於XML中配置的beans；@Bean標注方法等同於XML中配置的bean
4.啟動類啟動Swagger2（啟動類中加入@EnableSwagger2 代表swagger開啟:）
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
public class StudyprojectApplication {
public static void main(String[] args) {
SpringApplication.run(StudyprojectApplication.class, args);
}
}
5.定義Restful風格接口
import com.alibaba.fastjson.JSONObject;
import com.iflytek.studyproject.bean.Swagger2Bean;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/swagger2Controller")
public class Swagger2TestController {
@PostMapping("/getSwagger2")
public JSONObject getSwagger2(Swagger2Bean swagger2Bean){
JSONObject put = (JSONObject) new JSONObject().put(swagger2Bean.getId(), swagger2Bean.getName());
return put;
}
}
6.啟動
啟動項目訪問 http://localhost:8080/swagger-ui.html
7.Swagger2常用注解
- @Api()用於類；
表示標識這個類是swagger的資源
- @ApiOperation()用於方法；
表示一個http請求的操作
- @ApiParam()用於方法，參數，字段說明；
表示對參數的添加元數據（說明或是否必填等）
- @ApiModel()用於類
表示對類進行說明，用於參數用實體類接收
- @ApiModelProperty()用於方法，字段
表示對model屬性的說明或者數據操作更改
- @ApiIgnore()用於類，方法，方法參數
表示這個方法或者類被忽略
- @ApiImplicitParam() 用於方法
表示單獨的請求參數
- @ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam
具體使用舉例說明：
@Api()
用於類；表示標識這個類是swagger的資源
tags–表示說明
value–也是說明，可以使用tags替代
但是tags如果有多個值，會生成多個list