蓝易云

Swagger 与 OpenAPI

230次阅读
没有评论

共计 3823 个字符,预计需要花费 10 分钟才能阅读完成。

一、区别与联系

OpenAPI 3.x 规范是从 Swagger 2.x 分支出来的,主要是由 Linux 基金会的 OpenAPI Initiative 进行维护的。Swagger 2.x 规范被 OpenAPI 3.x 取代,OpenAPI 3.0 成为新的 API 规范标准。但Swagger 2.x 规范仍然被广泛使用,例如常见的 @Api​、@ApiOperation​ 等注解都是 Swagger 2.x 的内容。

功能/特性 Swagger 2.x 注解 OpenAPI 3.x 注解
类级别描述 @Api @Tag
方法级别描述 @ApiOperation @Operation
参数描述 @ApiParam @Parameter
响应描述 @ApiResponse @ApiResponse
数据模型描述 @ApiModel @Schema
数据模型属性描述 @ApiModelProperty @Schema
接口返回类型 @ApiResponse @ApiResponse
全局参数描述 @ApiImplicitParam 不需要使用,参数直接通过 @Parameter​ 注解定义

OpenAPI 3.x

引入依赖:

        <!-- Swagger 相关依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

配置类

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) // 扫描所有 API 接口
                .paths(PathSelectors.any()) // 所有路径都生成文档
                .build();
    }

    // 添加 API 信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xx管理系统接口文档")
                .description("xx管理系统相关接口的文档")
                .termsOfServiceUrl("https://www.amjun.com")
                .version("1.0")
                .build();
    }
}

在主程序上添加 @EnableOpenApi​ 注解。(不确定是否需要)

访问 ui 的路径为:/swagger-ui/index.html​,openapi 的 json 格式文档路径:/v3/api-docs

Swagger 与 OpenAPI

Swagger2.x

引入依赖:

        <!-- Swagger 相关依赖 -->
        <!-- Swagger UI for API documentation interface -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version> <!-- 选择合适的版本 -->
        </dependency>

        <!-- Swagger UI Starter (提供 Swagger UI 界面) -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

配置类:

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) // 扫描所有 API 接口
                .paths(PathSelectors.any()) // 所有路径都生成文档
                .build();
    }

    // 添加 API 信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xx管理系统接口文档")
                .description("xx管理系统相关接口的文档")
                .termsOfServiceUrl("https://www.amjun.com")
                .version("1.0")
                .build();
    }
}

访问 ui 的路径为:/swagger-ui.html

二、Swagger2.x 常用注解

1. @Api

  • 用于标记一个类作为 Swagger 的资源类。
  • 该注解一般用于 Controller 类上,用来说明该类是提供 RESTful API 的地方。
import io.swagger.annotations.Api;

@Api(tags = "用户管理接口", description = "提供用户相关的 CRUD 操作")
@RestController
@RequestMapping("/users")
public class UserController {
    // API 端点
}

2. @ApiOperation

  • 用于标记 Controller 方法,描述该方法的作用。
  • value:接口的方法描述。
  • notes:对接口方法的详细说明。
import io.swagger.annotations.ApiOperation;

@ApiOperation(value = "获取用户详情", notes = "根据用户 ID 获取用户的详细信息")
@GetMapping("/{id}")
public User getUserById(@PathVariable Long id) {
    return userService.getUserById(id);
}

3. @ApiParam

  • 用于标注方法参数,描述该参数的详细信息。
  • value:描述参数。
  • required:标记该参数是否是必填项。
import io.swagger.annotations.ApiParam;

@GetMapping("/{id}")
public User getUserById(
    @ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
    return userService.getUserById(id);
}

三、集成其他ui

1. bootstrap-ui

集成:

        <!-- Swagger 相关依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

       <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

访问 /doc.html 即可查看。

Swagger 与 OpenAPI

2. Knife4j

项目地址:https://doc.xiaominfo.com/

knife4j 的前身是 swagger-bootstrap-ui, 而 swagger-bootstrap-ui 是一个纯 swagger-ui 的皮肤项目。后续为了满足需求,不得不编写 java 代码,所以在swagger-bootstrap-ui 的 1.8.5~1.9.6 版本之间,采用的是后端 Java 代码和 UI 都混合在一个 jar 包。

这种方式只需要引入 jar 包即可,但是在微服务架构下显得有些臃肿。因此正式将项目改名 knife4j。(作者希望做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端.)

swagger-bootstrap-ui 的所有特性都会集中在 knife4j-spring-ui 包中,后端 java 代码和 ui 包分离为多个模块的 jar 包,以面对在目前微服务架构下,更加方便的使用增强文档注解(使用SpringCloud微服务项目,只需要在网关层集成UI的 jar 包即可,因此分离前后端)

Swagger 与 OpenAPI

集成:

        <!-- Swagger 相关依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

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

同样访问 /doc.html 即可。

Swagger 与 OpenAPI

AD:【腾讯云服务器大降价】2核4G 222元/3年 1核2G 38元/年
正文完
 0
阿蛮君
版权声明:本站原创文章,由 阿蛮君 于2024-11-28发表,共计3823字。
转载说明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。
评论(没有评论)
Copyright © 2022-2024 阿蛮君博客 湘ICP备2023001393号
本网站由 亿信互联 提供云计算服务 | 蓝易云CDN 提供安全防护和加速服务
Powered by Wordpress  Theme by Puock