當前位置:網站首頁>使用Swagger2實現RESTful文檔

使用Swagger2實現RESTful文檔

2022-01-27 01:23:22 辰遠YIL

1 RESTful API

2.1 RESTful API的基本規範

/api/版本號/資源

(2)請求方法:

GET: 查詢數據
POST: 提交新數據
PUT: 修改數據
DELETE: 删除數據

2.2 統一數據返回格式

(1)ApiResult:封裝Api返回結果

public class ApiResult<T> {
 public ApiResult() {}
 public ApiResult(boolean ok, int code, T data, String message) {
 super();
 this.ok = ok;
 this.code = code;
 this.data = data;
 this.message = message;
 }
 //處理是否成功
 private boolean ok;
 //結果狀態號,類比Http狀態碼
 private int code;
 //返回的結果數據
 private T data;
 //返回消息
 private String message;
 // 省略 getter 和 setter......
}

(2)ApiResultGenerator:提供工廠方法快速返回Api結果

public class ApiResultGenerator {
 private static final String DEFAULT_MESSAGE_SUCCESS = "SUCCESS"; //成功
 private static final String DEFAULT_MESSAGE_FAIL = "FAIL"; //失敗
 private static final int RESULT_CODE_SUCCESS = 200; //成功
 private static final int RESULT_CODE_SERVER_ERROR = 500; //服務
 //...省略其它常量
 public static <T> ApiResult<T> success(T data){ //成功
 return new ApiResult<T>(true, RESULT_CODE_SUCCESS, data, DEFAULT_MESS
 }
 public static <T> ApiResult<T> success(){ //成功
 return new ApiResult<T>(true, RESULT_CODE_SUCCESS, null, DEFAULT_MESS
 }
 public static <T> ApiResult<T> error(String message){ //失敗
 return new ApiResult<T>(false, RESULT_CODE_SERVER_ERROR, null, messag
 }
 public static <T> ApiResult<T> error(){ //失敗
 return new ApiResult<T>(false, RESULT_CODE_SERVER_ERROR, null, DEFAUL
 }

2 Swagger-UI的使用

前後端分開開發中,前端人員需要异步調用後端發布的RESTful API服務,後端服務繁 多,清晰同步的API文檔對於前端開發人員非常重要。Swagger是一款RESTful接口的文 檔在線自動生成+功能測試功能軟件。Spring可以非常方便的和Swagger集成,實現API 文檔的自動生成和發布。

2.1 Swagger-UI 常用注解

詳見:https://cloud.tencent.com/developer/article/1451907

2.2 Spring整合Swagger-UI (1)添加依賴

<!-- Swagger-UI -->
 <dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.8.0</version>
 </dependency>
 <dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.8.0</version>
 </dependency>

 (2)配置Swagger 添加配置類:Swagger2Config.java

@Configuration
@EnableSwagger2
public class Swagger2Config {
 @Bean
public Docket createRestApi() {
 return new Docket(DocumentationType.SWAGGER_2)
 .apiInfo(apiInfo())
 .select()
 //為當前包下controller生成API文檔
 .apis(RequestHandlerSelectors.basePackage("funnyshop.web.api"
 //為有@Api注解的Controller生成API文檔
 .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
 //為有@ApiOperation注解的方法生成API文檔
 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperati
 .paths(PathSelectors.any())
 .build();
 }
 private ApiInfo apiInfo() {
 return new ApiInfoBuilder()
 .title("FunnShop後端接口")
 .description("funnyshop-jee")
 .version("1.0")
 .build();
 }
}

 在SpringBoot啟動類中啟用Swagger

@MapperScan("funnyshop.mapper")
@SpringBootApplication
@EnableSwagger2 //啟用Swagger2
public class FunnyshopJeeApplication {
 public static void main(String[] args) {
 SpringApplication.run(FunnyshopJeeApplication.class, args);
 }
}

(3)為RESTful API控制器標記文檔

 (4)為數據對象標記文檔

 (5)查看API文檔 啟動項目,訪問:http://localhost:8080/swagger-ui.html

Swagger不僅提供查看文檔功能,還可以直接測試,點擊 “try it out!” 按鈕即可。

            ------------------------------------------------------------------------------------------

@ApiOperation("根據商品名稱模糊查詢商品列錶")
 @GetMapping("")
 @ApiImplicitParams({@ApiImplicitParam(name = "name", value="商品名稱,模糊
 public List<Product> findByName(String name){
 return productBiz.findProducts(name);
 }

版權聲明
本文為[辰遠YIL]所創,轉載請帶上原文鏈接,感謝
https://cht.chowdera.com/2022/01/202201270123218931.html

隨機推薦