文章目錄
Swagger2的誕生就是爲了解決前後端開發人員進行交流的時候API文檔難以維護的痛點,它可以和我們的Java程序完美的結合在一起,並且可以與我們的另一開發利器Spring Boot來配合使用。
項目實戰
創建Spring Boot項目
- 然後一直下一步就可以創建好了。
導入POM文件
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.3.0.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.carroll</groupId>
<artifactId>swagger-demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>swagger-demo</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
<exclusions>
<exclusion>
<groupId>org.junit.vintage</groupId>
<artifactId>junit-vintage-engine</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
編寫SwaggerConfig 配置類
package com.carroll.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
import java.util.ArrayList;
@Configuration
@EnableSwagger2 //開啓Swagger2
public class SwaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
private ApiInfo apiInfo(){
Contact contact = new Contact("Carrol", "https://www.baidu.com", "[email protected]");
return new ApiInfo("Carroll的Swagger的API文檔",
"你知道的越多,你不知道的越多。",
"V1.0",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
編寫User 實體類
package com.carroll.swagger.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("用戶實體類")
public class User {
@ApiModelProperty("用戶名")
private String name;
@ApiModelProperty("密碼")
private String password;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}
編寫Controller層
package com.carroll.swagger.controller;
import com.carroll.swagger.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Api(description = "控制層")
public class HelloController {
@ApiOperation("hello方法")
@GetMapping(value = "/hello")
public String hello(){
return "hello";
}
@PostMapping(value = "/user")
public User user(){
return new User();
}
}
運行
- 訪問:
http://localhost:8080/swagger-ui.html#/
- 到這兒就大功告成了,你的項目已經集成了Swagger了,下面我們在詳細解釋一下Swagger2的Api的作用,順便你也複習一下。
Swagger2 註解說明
@Api
@Api:用在請求的類上,表示對類的說明
tags="說明該類的作用,可以在UI界面上看到的註解"
value="該參數沒什麼意義,在UI界面上也看到,所以不需要配置"
@ApiOperation
@ApiOperation:用在請求的方法上,說明方法的用途、作用
value="說明方法的用途、作用"
notes="方法的備註說明"
@ApiImplicitParams
@ApiImplicitParams:用在請求的方法上,表示一組參數說明
@ApiImplicitParam:用在@ApiImplicitParams註解中,指定一個請求參數的各個方面
name:參數名
value:參數的漢字說明、解釋
required:參數是否必須傳
paramType:參數放在哪個地方
· header --> 請求參數的獲取:@RequestHeader
· query --> 請求參數的獲取:@RequestParam
· path(用於restful接口)--> 請求參數的獲取:@PathVariable
· body(不常用)
· form(不常用)
dataType:參數類型,默認String,其它值dataType="Integer"
defaultValue:參數的默認值
@ApiResponses
@ApiResponses:用在請求的方法上,表示一組響應
@ApiResponse:用在@ApiResponses中,一般用於表達一個錯誤的響應信息
code:數字,例如400
message:信息,例如"請求參數沒填好"
response:拋出異常的類
@ApiModel
@ApiModel:用於響應類上,表示一個返回響應數據的信息
(這種一般用在post創建的時候,使用@RequestBody這樣的場景,
請求參數無法使用@ApiImplicitParam註解進行描述的時候)
@ApiModelProperty:用在屬性上,描述響應類的屬性
你知道的越多,你不知道的越多。
有道無術,術尚可求,有術無道,止於術。
如有其它問題,歡迎大家留言,我們一起討論,一起學習,一起進步