Swagger使用的详细教程

一、背景介绍

        1.1、Swagger介绍

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

1.2、Swagger主要功能和用途:

  1. API设计:Swagger允许开发人员使用简洁的语法定义API的接口、参数、数据模型等信息,提供了一种标准化的方式来描述API的结构。
  2. 自动化文档生成:Swagger可以根据API定义自动生成交互式文档,包括API的终端点、参数、请求示例、响应示例等,方便开发人员和用户查阅和理解API的用法。
  3. 客户端代码生成:Swagger可以根据API定义生成客户端代码,支持多种编程语言和平台,简化客户端与API的交互过程。
  4. API测试:Swagger可以通过交互式文档提供API的测试界面,方便开发人员进行接口测试和调试。
  5. 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");
    }

效果如下: 

 

九、一些常用的注解

在上面的操作过程中,我们发现接口的一些信息都是英文的,不利于测试人员的阅读,所以我们为了增加接口文档的可读性,会使用一些注解,来达到这样的目的:

Swagger常用的注解分为两类:API注解和Model注解。

API注解:

  1. @Api:用于描述整个Controller或者某个接口的信息。
  2. @ApiOperation:用于描述接口的操作,包括接口名称、接口描述、请求方式、请求URL、请求参数、响应结果等。
  3. @ApiParam:用于描述接口中的参数信息,包括参数名称、参数描述、是否必填等。
  4. @ApiImplicitParam:用于描述接口中的参数信息,与@ApiParam类似,但更加灵活,可以支持更多的参数类型和传递方式。
  5. @ApiModel:用于描述数据模型(DTO),包括模型名称、描述、属性等。
  6. @ApiModelProperty:用于描述数据模型中的属性,包括属性名称、描述、数据类型、是否必填等。

Model注解:

  1. @ApiModel:用于描述数据模型(DTO),包括模型名称、描述、属性等。
  2. @ApiModelProperty:用于描述数据模型中的属性,包括属性名称、描述、数据类型、是否必填等。

下面展示常用的3个注解:

这里需要注意的是返回值存在实体类,该实体类才会被swagger扫描到!!!!!!

以上就是swagger介绍的全部内容。

注意在项目发布的时候需要更改项目的一个上线情况。

评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值