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文件中导入相关依赖:

        
            com.github.xiaoymin
            knife4j-spring-boot-starter
        

SpringBoot项目中使用Swagger_第1张图片

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;
    }
SpringBoot项目中使用Swagger_第2张图片
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/");
    }

SpringBoot项目中使用Swagger_第3张图片

四、访问

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

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

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

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

SpringBoot项目中使用Swagger_第4张图片

 五、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注解来满足特定的文档需求。

你可能感兴趣的:(spring,boot,后端,java,postman,yapi)