Swagger使用的详细教程

最新推荐文章于 2024-05-23 10:13:55 发布

小俞不多余

最新推荐文章于 2024-05-23 10:13:55 发布

阅读量1.6k

点赞数 20

文章标签： java

本文链接：https://blog.csdn.net/mkmmkkghhhhhhhh/article/details/135582803

版权

一、背景介绍

1.1、Swagger介绍

Swagger是一个开源的规范和工具集，用于设计、构建和文档化 RESTful API。它提供了一种简单易懂的方式来描述API的结构、请求和响应参数以及其它相关信息。通过使用Swagger，开发人员可以更加轻松地设计和开发API，并生成交互式文档，使得API的使用者能够快速了解和调用API。

1.2、Swagger主要功能和用途：

API设计：Swagger允许开发人员使用简洁的语法定义API的接口、参数、数据模型等信息，提供了一种标准化的方式来描述API的结构。
自动化文档生成：Swagger可以根据API定义自动生成交互式文档，包括API的终端点、参数、请求示例、响应示例等，方便开发人员和用户查阅和理解API的用法。
客户端代码生成：Swagger可以根据API定义生成客户端代码，支持多种编程语言和平台，简化客户端与API的交互过程。
API测试：Swagger可以通过交互式文档提供API的测试界面，方便开发人员进行接口测试和调试。
API管理：Swagger可以集成到API管理平台中，提供API的注册、发布、监控和权限控制等功能，方便对API进行管理和维护。

二、创建项目

三、配置Swagger信息

在pom文件下添加对应的maven包

        <!--swagger包-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

接着编写Swagger配置类

然后启动项目，访问链接http://localhost:8080/swagger-ui.html

这里有的在springboot版本大于2.6.1的时候会出现空指针报错

Failed to start bean 'documentationPluginsBootstrapper'; 
nested exception is java.lang.NullPointerException

解决方法有两个，一是降低springboot版本，二是添加两个配置文件

降低springboot版本这里不做介绍，介绍的是添加配置文件解决方法

首先在启动类中添加@EnableWebMvc注解

接着添加一个配置文件

@Configuration
public class WebMVCConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        /**
         * 配置swagger-ui显示文档
         */
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

这样就能解决空指针报错了

四、更改文档信息：

在swagger配置类里面写docket的方法

@Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("小俞", "", "");
        return new ApiInfo("小俞的swaggerApi文档",
                "这个是一个描述",
                "1.0版本号",
                "地址",
                contact, "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

重启项目之后，文件的信息就会进行更改：

五、配置扫描路径

public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                // RequestHandlerselectors.配罩要扫播接口的方式
                // basePackage("com.example.demo3"):指定要扫描的包
                // any ():扫描全部
                //none():个扫描
                //withclassAnnotation，扫描类上的注解，参数足一个注解的反射对象 withClassAnnotation(RestController.class) 扫描类上有RestController注解的类
                // withMethodAnnotation:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.example.demo3"))
                //过滤路径 ant("/code/**")只扫描带有code的路径的注解
                //.paths(PathSelectors.ant("/code/**"))
                .build();
    }

扫描的路径一定要在select和build两个方法里面，这样才能定义到

六、配置使用范围

swagger如果在项目发布的时候，还能访问，这样我们就会有接口暴露的风险，所以这里我们就可以配置在特定的情况下，无法使用swagger

这里我们使用多个配置文件

其他三个包配置的仅是端口不一致即可，这样我们就可以在配置文件中，获取当前项目的一个发布情况

这样即可，后续如果说我们项目发布了，就可以把配置文件里面的信息进行对应的更改即可。

七、自定义组名

自定义组名只需要通过内置的groupName即可

效果如下：

八、配置多个分组

我们做一个项目的时候肯定是进行一个团队的开发形式，所以为了管理自己的接口，我们有必要的就是进行多个组的管理，多个组的形式就是创建多个bean实例即可：

@Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("A1");
    }
    @Bean
    public Docket docket3() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("A2");
    }

效果如下：