前言

在前面的部落格中，我們將服務註冊到了Eureka上，可以從Eureka的UI介面中，看到有哪些服務已經註冊到了Eureka Server上，但是，如果我們想檢視當前服務提供了哪些RESTful介面方法的話，就無從獲取了，傳統的方法是梳理一篇服務的介面文件來供開發人員之間來進行交流，這種情況下，很多時候，會造成文件和程式碼的不一致性，比如說程式碼改了，但是介面文件沒有改等問題，而Swagger2則給我們提供了一套完美的解決方案，下面，我們來看看Swagger2是如何來解決問題的。

一、引入Swagger2依賴的jar包

<!-- swagger2 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.2.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.2.2</version>
		</dependency>
 

@Configuration
@EnableSwagger2 // 啟用Swagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {// 建立API基本資訊
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chhliu.jpa"))// 掃描該包下的所有需要在Swagger中展示的API，@ApiIgnore註解標註的除外
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {// 建立API的基本資訊，這些資訊會在Swagger UI中進行顯示
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構建RESTful APIs")// API 標題
                .description("rdcloud-jpa提供的RESTful APIs")// API描述
                .contact("
 
[email protected]")// 聯絡人
                .version("1.0")// 版本號
                .build();
    }

}

三、完善API文件資訊

public interface SonarControllerI {
	@ApiOperation(value="獲取專案組Sonar對應的Url資訊", notes="根據id獲取專案組Sonar對應的Url資訊")// 使用該註解描述介面方法資訊
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "SonarUrl表ID", required = true, dataType = "Long", paramType="path")
    })// 使用該註解描述方法引數資訊，此處需要注意的是paramType引數，需要配置成path，否則在UI中訪問介面方法時，會報錯
	@GetMapping("/get/{id}")
	SonarUrl get(@PathVariable Long id);
	
	@ApiOperation(value="獲取專案組Sonar對應的所有Url資訊")
	@GetMapping("/get/all")
	List<SonarUrl> getAll();
}
 

注：paramType表示引數的型別，可選的值為"path","body","query","header","form"

四、完善返回型別資訊

@Entity(name = "SONAR_URL")
public class SonarUrl implements Serializable {

	/**
	 * 
	 */
	private static final long serialVersionUID = 1L;
	@ApiModelProperty(value="主鍵", hidden=false, notes="主鍵，隱藏", required=true, dataType="Long")// 使用該註解描述屬性資訊,當hidden=true時，該屬性不會在api中顯示
	@Id
	@GeneratedValue(strategy = GenerationType.AUTO)
	private Long id;
	
	@ApiModelProperty(value="URL連結地址")
	@Column(name="URL")
	private String url;
	
	@ApiModelProperty(value="專案組")
	@Column(name="TEAM")
	private String team;

	@ApiModelProperty(value="部門")
	@Column(name="DEPARTMENT")
	private String department;
        ……省略getter，setter方法……
 }

1、在瀏覽器中輸入：http://localhost:7622/swagger-ui.html

2、結果如下：

六、API文件訪問與測試

Swagger除了提供API介面檢視的功能外，還提供了除錯測試功能

測試結果如下：