您的位置:

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