详解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的开发效率和质量。