Swagger 介面文件
阿新 • • 發佈:2022-03-15
目錄
Swagger 介紹
Swagger UI 允許任何人(無論是開發團隊還是終端使用者)都可以視覺化 API 資源並與之互動,而無需任何實現邏輯。
Swagger API 文件是根據 OpenAPI(以前稱為 Swagger)規範自動生成的,可簡化後端實現和客戶端的使用。
Swagger 依賴
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-bean-validators</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> <version>1.5.21</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> <version>1.5.21</version> </dependency>
SpringBoot 整合 Swagger 配置類
package com.example.apitestplatform.config; import com.google.common.collect.Lists; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.ParameterBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.schema.ModelRef; 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; /** * Swagger 文件配置類 */ @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket docket() { ParameterBuilder builder=new ParameterBuilder(); builder.parameterType("header") .name("token") .description("token值") .required(true) .modelRef(new ModelRef("string")); // 在swagger文件裡展示header return new Docket(DocumentationType.SWAGGER_2) .groupName("ApiDemo") .apiInfo(apiInfo()) .globalOperationParameters(Lists.newArrayList(builder.build())) .select() // 選擇生成策略 .apis(RequestHandlerSelectors.basePackage("com.example.apitestplatform.controller")) // 選擇生成文件的類(忽略該行則不做過濾) .paths(PathSelectors.any()) .build(); } // 定義介面文件基本資訊 private ApiInfo apiInfo(){ return new ApiInfoBuilder() .title("ApiDemo 系統") // 介面文件標題 .description("ApiDemo 介面文件") // 介面文件描述 .contact(new Contact("xiaoming", "", "[email protected]")) // 作者聯絡方式 .version("1.0") // 介面文件版本 .build(); } }
常用註解
- @Api(tags="API 類標題")
- @ApiOperation(value="API 方法標題")
- @ApiModel(value="實體類標題", description="實體類描述")
- @ApiModelProperty(value="實體屬性描述",example="屬性示例取值", required=true)
示例:
- 介面類:
package com.example.apitestplatform.controller; import com.example.apitestplatform.entity.User; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.beans.factory.annotation.Value; import org.springframework.web.bind.annotation.*; @Api(tags="Swagger Demo 類") @RestController @RequestMapping(value="demo") // 類中所有介面地址的字首 public class DemoController { @Value("${user.hobby}") private String hobby; @ApiOperation(value="Swagger Demo get方法") // @RequestMapping(value="loginGet", method= RequestMethod.GET) @GetMapping("loginGet") public String loginGet() { return hobby; } // @RequestMapping(value="loginPost", method= RequestMethod.POST) @PostMapping("loginPost") // 簡便寫法 public String loginPost(@RequestBody User user) { // 如果沒用 @RequestBody,則獲取結果為 null System.out.println("username : "+user.getUsername()); System.out.println("password : "+user.getPassword()); return "登入成功:"+user.getUsername(); } // 訪問:http://localhost:8080/demo/userId/1/2 // @RequestMapping(value="userId/{userId}/{id}", method=RequestMethod.GET) @GetMapping("getUser/{userid}/{id}") public String loginUser1(@PathVariable("userid") Integer userid, @PathVariable("id") Integer id) { System.out.println("userid : "+userid); System.out.println("id : "+id); return "userid: "+userid+" id: "+id; } // 訪問:http://localhost:8080/demo/getUser?userid=1&id=2 // 訪問:http://localhost:8080/demo/getUser?user=1&id=2,則 userid 值為 null @GetMapping("getUser") public String loginUser2(@RequestParam(value="userid", required=false) Integer userid, // required=false:引數非必須傳 @RequestParam("id") Integer id) { System.out.println("userid : "+userid); System.out.println("id : "+id); return "userid: "+userid+" id: "+id; } }
- User 類:
package com.example.apitestplatform.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@ApiModel(value="使用者類", description="使用者資訊")
@Data
public class User {
@ApiModelProperty(value="使用者名稱", example="xiaoming", required=true)
private String username;
@ApiModelProperty(value="密碼", example="123456", required=true)
private String password;
}