→ springboot 集成 Swagger2 ←

目录

1. 案例

这次直接使用 2.5.6 的 spring-boot 。

  1. 依赖：

        <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.5.6</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--swagger3-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>

  2. 启动类加注解 @EnableOpenApi

  3. 新建测试类

    @RestController
@RequestMapping("/test")
public class SwaggerController {
    @GetMapping("/get")
    public String getStr(String str) {
        return "SELECT " + str;
    }

    @PostMapping("/post")
    public String postStr(String str) {
        return "CREATE " + str;
    }

    @PutMapping("/put")
    public String putStr(String str) {
        return "UPDATE " + str;
    }

    @NoSwagger
    @PatchMapping("/patch")
    public String patchStr(String str) {
        return "UPDATE " + str;
    }

    @DeleteMapping("/delete")
    public String deleteStr(String str) {
        return "DELETE " + str;
    }
}

  4. 访问 http://127.0.0.1:8080/swagger-ui.html ，没错，又是 Error 页面

此部分参考：https://blog.csdn.net/mmmm0584/article/details/117786055

在swagger3.0中，swagger-ui.html的位置发生了变化：
  →  
所以路径也变了：http://127.0.0.1:8080/swagger-ui.html → http://127.0.0.1:8080/swagger-ui/index.html

  1. 访问 http://127.0.0.1:8080/swagger-ui/index.html

2. info 配置

新建一个配置类：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.HashSet;

@Configuration
public class Swagger3Conf {
    @Bean
    public Docket createDocket() {
        return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本号
                .apiInfo(createApiInfo());
    }

    @Bean
    public ApiInfo createApiInfo() {
//        // 写法一
//        return new ApiInfoBuilder()
//                .title("Swagger3 文档案例")
//                .description("Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。")
//                .version("1.0.1")
//                .contact(
//                        // name url email
//                        new Contact("364.99°的文档", // 文档发布者名称
//                                "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
//                                "2190826197@qq.com" // 文档发布者的邮箱
//                        )
//                )
//                .build();
        // 写法二
        return new ApiInfo(
                "Swagger3 文档案例",
                "Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。",
                "1.0.1",
                "https://blog.csdn.net/m0_54355172",
                new Contact("364.99°的文档", // 文档发布者名称
                                "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
                                "2190826197@qq.com" // 文档发布者的邮箱
                        ),
                "364.99°",
                "https://blog.csdn.net/m0_54355172",
                new HashSet<>());
        }
}

  • Docket Swagger 的实例，可通过 Docket 对象来配置 Swagger；
  • ApiInfo 文件描述的配置对象。

3. Docket 配置

1. 开关配置

    @Bean
    public Docket createDocket() {
        return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本号
                .enable(false)// 关闭文档
                .apiInfo(createApiInfo());
    }

注意： 一般只有在测试环境才会用到 Swagger，在生产环境中会把它关闭掉，为了安全与效率。

2. 扫描路径

                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger2.controller"))
                .build()

3. 路径匹配

新建一个控制器：

@Api(tags = "other 接口 API")
@RestController
@RequestMapping("/other")
public class OtherController {
    @GetMapping("getInfo")
    public String getInfo() {
        return "information";
    }
}

                .select()
                .paths(PathSelectors.ant("/other/**"))
                .build()

4. 分组管理

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.HashSet;

@Configuration
public class Swagger3Conf {
    @Bean
    public Docket createDocket01() {
        return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本号
                .groupName("other 组")
                .enable(true)// 关闭文档
                .select()
                .paths(PathSelectors.ant("/other/**"))
                .build()
                .apiInfo(createApiInfo());
    }

	@Bean
    public Docket createDocket02() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("test 组")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger2.controller"))
                .build()
                .apiInfo(
                        new ApiInfoBuilder()
                                .title("Swagger3 文档案例")
                                .build()
                );
    }

    @Bean
    public ApiInfo createApiInfo() {
//        // 写法一
//        return new ApiInfoBuilder()
//                .title("Swagger3 文档案例")
//                .description("Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。")
//                .version("1.0.1")
//                .contact(
//                        // name url email
//                        new Contact("364.99°的文档", // 文档发布者名称
//                                "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
//                                "2190826197@qq.com" // 文档发布者的邮箱
//                        )
//                )
//                .build();
        // 写法二
        return new ApiInfo(
                "Swagger3 文档案例",
                "Swagger ：一套围绕 Open API 规范构建的一款 RESTful 接口的文档在线自动生成和功能测试 API 。",
                "1.0.1",
                "https://blog.csdn.net/m0_54355172",
                new Contact("364.99°的文档", // 文档发布者名称
                                "https://blog.csdn.net/m0_54355172", // 文档发布者的网站地址
                                "2190826197@qq.com" // 文档发布者的邮箱
                        ),
                "364.99°",
                "https://blog.csdn.net/m0_54355172",
                new HashSet<>());
        }
}

4. 常用注解

1. 说明

和 Swagger2 一样，其常用注解还是如下几个：

常用注解注解说明常用属性属性说明
@Api类注解，常用来给文档中的控制器取别名tags别名
@ApiOperation方法/类注解，常用来描述方法value
notes		方法说明
方法备注
@ApiParam参数/方法/属性注解，常用来描述参数name
value
required		参数名
补充描述
是否必须
@ApiIgnore方法/属性注解，使被标注方法不生成文档--
@ApiImplicitParam方法注解，描述一个参数name
value
name
required
paramType
dataType
defaultValue		参数名
补充说明

是否必传
参数位置（header、query、path）
参数类型（默认 String）
默认值
@ApiImplicitParams搭配 @ApiImplicitParam 一起使用，描述一组参数
@ApiResponse方法注解，表达一个错误的响应信息code
message
response		整型
字符串
异常信息（默认 String 类型）
@ApiResponses搭配 @ApiResponse 一起使用，参考 @ApiImplicitParams
@ApiModel类注解，当此实体类被作为返回类型用于 API 帮助文档中的接口方法中，此注解被解析value
description		实体类名
补充描述
@ApiModelProperty属性注解，搭配 @ApiModel 使用value
example
hidden		属性名
示例
是否隐藏

2. 案例

import com.chenjy.swagger2.dto.TestDto;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

@Api(tags = {"test 接口 API"})
@RestController
public class SwaggerController {

    @ApiResponses({
            @ApiResponse(code = 1, message = "查询成功"),
            @ApiResponse(code = -1, message = "查询失败")
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "角色名", required = false, defaultValue = "张三"),
            @ApiImplicitParam(name = "num", value = "序列号", required = true)
    }
    )
    @PostMapping("/getInfo")
    public TestDto getInfo(String name, Integer num) {
        return new TestDto(name, num);
    }
    
    @ApiIgnore
    @GetMapping("/getStr")
    public String getStr(String name) {
        return name;
    }
}

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel( value = "角色实体类", description = "存储数据并返回")
public class TestDto {
    @ApiModelProperty( value = "姓名", example = "张三", hidden = false)
    private String name;
    @ApiModelProperty( value = "序列号", example = "1")
    private Integer num;
}
# spring boot
Logo
开放原子开发者工作坊

开放原子开发者工作坊旨在鼓励更多人参与开源活动，与志同道合的开发者们相互交流开发经验、分享开发心得、获取前沿技术趋势。工作坊有多种形式的开发者活动，如meetup、训练营等，主打技术交流，干货满满，真诚地邀请各位开发者共同参与！

更多推荐

2024开放原子开发者大会议题征集正式开启

2024开放原子开发者大会（以下简称“大会”）将于12月中旬重磅来袭,2024开放原子开发者大会议题征集正式开启!

avatar 开放原子开发者工作坊

操作系统大会&openEuler Summit 2024参会指南，请查收！

avatar 开放原子开发者工作坊

推动工业软件核心技术攻关，开源工业软件算法集成大赛正式启动！

推动工业软件核心技术攻关，开源工业软件算法集成大赛正式启动！

avatar 开放原子开发者工作坊