Swagger的基本使用_swagger docket-CSDN博客

本文链接：https://blog.csdn.net/ilove_story/article/details/109647148

1、概述

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger 的优势

支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

2、基本使用

2.1 环境搭建

创建一个SpringBoot项目，导入下列依赖

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
		<dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>

编写一个HelloController

@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String hello() {
        return "hello";
    }
}

启动项目，测试环境是否正常

2.2 配置swagger

创建一个SwaggerConfig配置类

@Configuration
@EnableSwagger2  //开启swagger2
public class SwaggerConfig {
    
}

接着，启动项目，输入:http://localhost:8080/swagger-ui.html，如果出现下列页面，表示配置成功：
在这里插入图片描述

2.3 自定义配置

如果想要自定义配置，需要创建一个Docket类型的bean实例

    //配置swagger的Docket实例
    @Bean
    public Docket docket() {
        //DocumentationType:文档类型
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        return docket;
    }

2.3.1 定义文档信息

@Bean
    public Docket docket() {
        //DocumentationType:文档类型
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInf());//配置文档信息
        return docket;
    }


//配置api文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("鹏哥","http://localhost:8080/hello","1980634728@xx.com");
        ApiInfo apiInfo = new ApiInfo("鹏哥的api文档", "描述信息", "1.0", "localhost:8080/hello", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
        return apiInfo;
}

2.3.2 配置扫描的接口

    @Bean
    public Docket docket() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                //配置接口文档信息
                .apiInfo(apiInfo())
                //配置扫描的接口
                .select()
                //RequestHandlerSelectors:配置要扫描接口的方式
                //basePackage:指定要扫描的包
                //any:扫描全部
                //none:不扫描
                //withClassAnnotation:扫描带有指定类注解的接口
                //withMethodAnnoation:扫描带有指定方法注解的
                .apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
                .build();

        return docket;
    }

2.3.3 配置是否开启swagger

配置是否开启只需要通过enable()方法传入一个布尔值即可，当设置为false时，就无法在浏览器中打开我们的swagger的ui界面了。这里我们配置只能在测试环境和开发环境下开启swagger，操作步骤如下：

首先，编写开发环境、生产环境和测试环境对应的配置文件,即application-dev.properties、application-prod.properties和application-test.properties，只需简单设置下端口号即可
接着在application.properties配置当前环境

spring.profiles.active=dev

然后修改SwaggerConfig配置类

@Bean
    public Docket docket(Environment environment) {
        //如果是dev环境或者test环境则开启
        Profiles profiles = Profiles.of("dev", "test");
        boolean flag = environment.acceptsProfiles(profiles);
        
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                //配置接口文档信息
                .apiInfo(apiInfo())
                //配置是否开启swagger
                .enable(flag)
                //配置扫描的接口
                .select()
                //RequestHandlerSelectors:配置要扫描接口的方式
                //basePackage:指定要扫描的包
                //any:扫描全部
                //none:不扫描
                //withClassAnnotation:扫描带有指定类注解的接口
                //withMethodAnnoation:扫描带有指定方法注解的
                .apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
                .build();

        return docket;
    }

2.3.4 配置分组

配置分组很简单，只需要一行代码即可：

.groupName("A")//分组的名字

如何配置多个分组呢？

    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }

    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

    @Bean
    public Docket docket3() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("D");
    }

在这里插入图片描述

2.4 常用注解

2.4.1 实体类注解

@ApiModel(description = "用户实体类")
@Data
public class User {
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "年龄")
    private Integer age;
}

需要注意，如果实体类类型不在控制层方法返回值类型中，就不会被扫描到，所以我们需要增加控制层方法

@RequestMapping("/hello2")
    public User hello2() {
        return new User();
}

2.4.2 控制层注解

 @ApiOperation(value = "hello2方法")
    @RequestMapping("/hello2")
    public User hello2(@ApiParam(value = "用户名") String username) {
        return new User();
}

在这里插入图片描述