Swagger工具的作用及使用方法

最新推荐文章于 2024-03-13 23:15:24 发布

程序猿Fly

最新推荐文章于 2024-03-13 23:15:24 发布

阅读量954

点赞数

分类专栏：初学者 java 文章标签：后端 java postman spring boot

本文链接：https://blog.csdn.net/qq_45880237/article/details/132176874

版权

初学者同时被 2 个专栏收录

2 篇文章 1 订阅

订阅专栏

java

2 篇文章 0 订阅

订阅专栏

前言，Swagger和Postman都是常用的API开发和测试工具,Swagger使开发人员在设计和开发API时，能够更好地进行接口文档的编写、展示和管理，以及提供在线接口测试的能力。其主要有以下功能：

自动生成接口文档：Swagger可以通过注解或配置文件的方式，从源代码中自动生成接口文档，包括接口名称、描述、请求参数、响应数据等信息。
在线文档展示：Swagger提供了一个直观的、可交互的接口文档界面，可以方便地查看和测试接口，而不需要像传统的文档一样要打开文档文件。
参数校验和模拟请求：Swagger可以对请求参数进行校验，并提供一个模拟请求的功能，使得开发人员可以在不依赖真实数据的情况下进行接口的测试。
接口版本管理：Swagger支持对接口的版本管理，以及对不同版本接口的文档的展示和对比，方便开发人员进行接口的迭代和升级。

以下将会介绍Swaager工具的使用方法及相应界面展示：

1.导入Swagger的maven坐标

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

2.在spring或springboot项目中定义一个配置类，用于配置Swagger生成接口文档的相关信息。首先，需要通过ApiInfoBuilder构建一个ApiInfo对象，设置接口文档的标题、版本、描述等信息。然后，创建一个Docket实例，并调用apiInfo方法将刚刚创建的ApiInfo对象传入，设置接口文档的基本信息。接下来，通过select方法选择要生成接口文档的接口，使用apis方法指定接口所在的包，使用paths方法指定接口的路径。最后，通过调用build方法构建一个完整的Docket对象，并将其返回。(不理解也没关系，这个配置比较固定，在实际的使用过程中只需要修改代码中的文本信息即可)

package com.zeng.config;

import com.sky.interceptor.JwtTokenAdminInterceptor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;


@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {
    /**
     * 通过knife4j生成接口文档
     * @return
     */
    @Bean
    public Docket docket() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("项目接口文档") //接口文档的标题
                .version("2.0")  //接口文档的版本
                .description("项目接口文档") //接口文档的相关描述
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zeng.controller")) //接口所在的包
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

3. 继续在配置类中配置静态资源映射的方法，这个方法通常会被放在一个继承自WebMvcConfigurerAdapter的配置类中，用于配置Spring MVC的一些额外设置。在这个方法中，使用了ResourceHandlerRegistry对象的addResourceHandler方法来指定资源的访问路径，addResourceLocations方法来指定本地资源的路径。具体来说，第一个addResourceHandler方法将路径"/doc.html"映射到"classpath:/META-INF/resources/"下的资源，第二个addResourceHandler方法将路径"/webjars/**"映射到"classpath:/META-INF/resources/webjars/"下的资源。这样做的目的是为了让Swagger UI（Swagger的前端界面）和相关静态资源能够被正确加载和访问。

    /**
     * 设置静态资源映射
     * @param registry
     */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // "/doc.html"是Swagger的访问路径
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

4. 以上配置完后，可直接在浏览器输入localhost:8080/doc.html访问Swagger页面。打开后可查看到以下信息。