詳解Swagger默認訪問地址

Swagger是一個用於構建、文檔化和測試RESTful Web服務的開源框架。默認情況下，Swagger會創建一個訪問地址，即localhost:8080/swagger-ui.html，其中包含API文檔和測試工具。本文將從多個方面對Swagger默認訪問地址進行詳細闡述，以便更好地了解和使用Swagger。

一、Swagger默認訪問地址的結構

默認訪問地址localhost:8080/swagger-ui.html由兩個部分組成：主機和路徑。主機為localhost，即本地主機，埠為8080。路徑為/swagger-ui.html，其中swagger-ui.html為Swagger提供的一個UI頁面，用於顯示API文檔和測試工具。

二、Swagger默認訪問地址的作用

Swagger默認訪問地址的作用是提供一個UI界面，讓用戶更方便地查看和測試API。用戶可以在UI界面中查看API文檔和測試API，而無需使用其他工具或手動編寫請求。此外，Swagger還提供了各種配置選項，使用戶可以自定義UI界面和API文檔。

三、訪問Swagger默認地址的方式

有多種方式可以訪問Swagger默認地址：

1. 在瀏覽器中輸入地址localhost:8080/swagger-ui.html

2. 在代碼中使用Swagger的API進行訪問，示例代碼如下：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() {                
        return new Docket(DocumentationType.SWAGGER_2)          
          .select()                                       
          .apis(RequestHandlerSelectors.basePackage("com.example.demo"))              
          .paths(PathSelectors.ant("/api/*"))                           
          .build();
    }
}

以上代碼是一個Spring Boot項目中訪問Swagger的配置文件，其中配置Swagger的API可以通過訪問localhost:8080/swagger-ui.html進行查看。

四、Swagger UI界面的使用

Swagger UI界面提供了許多功能，如搜索、請求管理、參數傳遞、API文檔查看等等。

1. 搜索功能

在Swagger UI界面的右上角，有一個搜索框，可用於查找特定API或操作。

2. 請求管理

在Swagger UI界面中，用戶可以通過「Try it out」按鈕測試API，並查看請求和響應的詳細信息。此外，請求和響應也可以保存為Curl命令或Postman集合。

3. 參數傳遞

Swagger UI界面允許用戶自定義請求參數，如請求頭、請求體、請求路徑參數等。

4. API文檔查看

在Swagger UI界面的左側，用戶可以查看API文檔，包括API名稱、API描述、請求方法、請求URL、請求參數、請求體等。

五、擴展Swagger默認訪問地址

Swagger默認訪問地址可以通過修改配置文件或編寫代碼的方式進行擴展。以下是兩種擴展方式的示例：

1. 修改配置文件

打開Swagger UI界面所在的配置文件，通常為application.yml或application.properties，添加以下配置：

# API文檔的title信息
springfox.documentation.swagger.v2.title=My API Document

# API文檔的版本信息
springfox.documentation.swagger.v2.version=1.0.0

# API文檔的描述信息
springfox.documentation.swagger.v2.description=This is a sample API document for demo purpose.

# API文檔的聯繫人信息
springfox.documentation.swagger.v2.contact=
    name: your name
    email: your email
    url: your url

# 要顯示的API文檔
springfox.documentation.swagger.v2.paths=/api/**

修改後，可以通過訪問localhost:8080/swagger-ui.html查看修改後的Swagger UI界面。

2. 編寫代碼

在Spring Boot項目中編寫以下代碼，實現自定義配置和路徑：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() {                
        return new Docket(DocumentationType.SWAGGER_2)          
          .select()                                       
          .apis(RequestHandlerSelectors.basePackage("com.example.demo"))              
          .paths(PathSelectors.ant("/api/*"))                           
          .build()
          .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API Document")
                .description("This is a sample API document for demo purpose.")
                .version("1.0.0")
                .contact(new Contact(
                        "your name",
                        "your url",
                        "your email"))
                .build();
    }
}

編寫完代碼後，可以通過訪問localhost:8080/swagger-ui.html查看修改後的Swagger UI界面。

六、小結

本文對Swagger默認訪問地址進行了詳細闡述，包括結構、作用、訪問方式、UI界面使用和擴展等方面。通過對Swagger的深入了解，可以更好地利用Swagger提供的API文檔和測試工具，提高API的開發效率和質量。