SpringBoot项目中使用Swagger

一、Swaggeer的介绍

        Swagger是一个用于构建API文档和客户端生成工具的开源项目。它提供了一个基于Web的接口，用于以简单且交互式的方式查看和测试API，同时还提供了一组用于生成客户端代码的工具。Swagger使用YAML格式定义API，并使用Markdown格式生成API文档。它支持多种编程语言，包括Java、Python、PHP、JavaScript等。Swagger的目标是提高API的可读性、可访问性和可重用性。

二、Swagger和Postman的区别

        Swagger是一个用于构建API文档和客户端生成工具的开源项目。它提供了一个基于Web的接口，用于以简单且交互式的方式查看和测试API，同时还提供了一组用于生成客户端代码的工具。Swagger使用YAML格式定义API，并使用Markdown格式生成API文档。它支持多种编程语言，包括Java、Python、PHP、JavaScript等。Swagger的目标是提高API的可读性、可访问性和可重用性。  Postman是一个用于测试API的客户端工具。它提供了一个用户友好的界面，用于发送HTTP请求并查看响应。Postman可以帮助您测试API的各个方面，包括功能、性能和安全性。它还提供了一些功能，例如自动凭证管理和会话管理，以帮助您更轻松地进行API开发和测试。Postman主要用于API的客户端测试，而Swagger提供了更全面的API开发和文档功能。  因此，Swagger和Postman的主要区别在于Swagger提供了更全面的API开发和文档功能，而Postman则更专注于API的客户端测试。根据项目的需求和阶段，您可以选择适合您的工具或同时使用这两个工具来满足您的API开发和测试需求。

三、Swagger的使用方式

1、导入knife4j的maven坐标

在你的pom文件中导入相关依赖：

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
        </dependency>

 

2、在配置类中加入knife4j相关配置

将要扫描的路径换成自己的！！！

    @Bean
    public Docket docket1() {
        log.info("准备生成接口文档...");
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("****项目接口文档")
                .version("2.0")
                .description("****项目接口文档")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("管理端接口")
                .apiInfo(apiInfo)
                .select()
//                指定生成接口需要扫描包
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

 

3、设置静态资源映射，否则接口文档页面无法访问

    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info("开始设置静态资源映射...");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

四、访问

这里访问的是doc.html，而前面的代码片段中有这样一句：

registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");

我想聪明的你应该会说：“我早就知道了~”

然后里面的大致轮廓就是这几个标出来的部分：

 

 五、Swagger的常用注解

1. @ApiOperation：用于描述API的操作名称、描述和参数。  

2. @ApiParam：用于描述API的参数名称、描述和位置。  3. @ApiResponses：用于描述API的响应集合，包括成功和失败的响应。  

4. @ApiResponse：用于描述API的单个响应，包括状态码和描述。  

5. @ApiModel：用于描述模型的结构和属性。  6. @ApiModelProperty：用于描述模型属性的名称、描述和是否必需。  

7. @Api、@ApiImplicitParam和@ApiImplicitParams：用于描述API的路径参数和请求体参数。  

8. @ApiResponses和@ApiResponse：用于描述WebMvcController的响应集合和单个响应。  

9. @ApiIgnore：用于忽略某个方法或属性。  

10. @ApiModelPropertyAccess和@ApiModelPropertyOrder：用于控制模型属性的访问级别和排序方式。  

        这些注解可以用于Java类、方法和参数上，以便将文档自动生成为Swagger UI。根据具体的需求和使用方式，还可以使用其他Swagger注解来满足特定的文档需求。