背景

有一个系统比较老，由于低版本spring有一些安全漏洞，需要升级jdk和springboot版本。老的项目使用的jax-rs暴漏的api，一开始考虑切换为spring rest api，这样文档直接引用springdoc-openapi-starter-webmvc-ui就搞定了，但是由于种种原因，最终需要沿用jax-rs。本文主要侧重说明springboot升级高版本后（jakarta.servlet），如何生成jax-rs/jersey接口swagger文档

swagger版本

2.2.22

引入swagger pom

由于springboot3.x版本使用的jakarta.servlet，所以引用如下包

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2-jakarta</artifactId>
    <version>2.2.22</version>
</dependency>

如果springboot是第版本，可以引用如下包

<dependency>
      <groupId>io.swagger.core.v3</groupId>
      <artifactId>swagger-jaxrs2</artifactId>
      <version>2.2.7</version>
    </dependency>

可以看下该包源码，关键点是io.swagger.v3.jaxrs2.integration.resources.OpenApiResource这个类，暴漏了openapi文档的访问入口

package io.swagger.v3.jaxrs2.integration.resources;

import io.swagger.v3.oas.annotations.Operation;

import jakarta.servlet.ServletConfig;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Application;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.HttpHeaders;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.core.UriInfo;

@Path("/openapi.{type:json|yaml}")
public class OpenApiResource extends BaseOpenApiResource {
    @Context
    ServletConfig config;

    @Context
    Application app;

    @GET
    @Produces({MediaType.APPLICATION_JSON, "application/yaml"})
    @Operation(hidden = true)
    public Response getOpenApi(@Context HttpHeaders headers,
                               @Context UriInfo uriInfo,
                               @PathParam("type") String type) throws Exception {

        return super.getOpenApi(headers, config, app, uriInfo, type);
    }
}

其他类主要是根据配置的包生成swagger文档，其实是生成openapi.json文件。此处不展开说明了 io.swagger.v3.jaxrs2.integration.JaxrsApplicationAndResourcePackagesAnnotationScanner

配置接口包路径

在项目资源文件路径下新增openapi-configuration.yaml文件

resourcePackages:
- io.swagger.sample.resource 替换为自己项目接口包路径，swagger会扫描该路径生成文档
prettyPrint: true
cacheTTL: 0
openAPI:
  info:
    version: '1.0'
    title: Swagger Pet Sample App Config File
    description: 'This is a sample server Petstore server.  You can find out more
      about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net,
      #swagger](http://swagger.io/irc/).  For this sample, you can use the api key
      `special-key` to test the authorization filters.'
    termsOfService: http://swagger.io/terms/
    contact:
      email: apiteam@swagger.io
    license:
      name: Apache 2.0
      url: http://www.apache.org/licenses/LICENSE-2.0.html

使swagger在项目中生效

将上面swagger暴漏的resource放到项目的上下文中，以jersey为例

public class MyApplication extends ResourceConfig {
    public MyApplication() {
        //下面两种方式二选一即可
        //直接注册该类
        register(io.swagger.v3.jaxrs2.integration.resources.OpenApiResource.class);
        //或者通过扫包方式
        packages("io.swagger.v3.jaxrs2.integration.resources")
    }
}

通过上面三个步骤就可以访问接口的json文件了,访问链接为http://localhost:8080/自己的项目路径/openapi.json

如果未生成接口的json文件，可能是swagger注解问题（新老版本注解有替换），也可能是链接地址不对

swagger1.x & 2.x注解替换详情如下

@Api → @Tag

@ApiIgnore→@Parameter(hidden = true)或@Operation(hidden = true)或@Hidden

@ApiImplicitParam → @Parameter

@ApiImplicitParams → @Parameters

@Schema → @Schema

@SchemaProperty(hidden = true) → @Schema(accessMode = READ_ONLY)

@SchemaProperty → @Schema

@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")

@ApiParam → @Parameter

@ApiResponse(code = 404+"", description = "foo") → @ApiResponse(responseCode = "404", description = "foo")

原文链接：https://blog.csdn.net/weixin_53618357/article/details/132672459

使用swagger-ui

以swagger-ui-dist方式举例

下载swagger-ui静态资源文件

下载地址

将静态文件放到项目中，springboot 默认静态文件路径 classpath:/META-INF/resources/ classpath:/resources/ classpath:/static/ classpath:/public/

比如放到/resources/docs目录下

修改文档路径

修改swagger-initializer.js文件，替换url为上一步生成的openapi.json的访问路径

window.onload = function() {
  //<editor-fold desc="Changeable Configuration Block">

  // the following lines will be replaced by docker/configurator, when it runs in a docker-container
  window.ui = SwaggerUIBundle({
    url: "http://localhost:8080/我的项目路径/openapi.json",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  });

  //</editor-fold>
};

配置项目静态文件访问

springboot中可以在application.properties文件中配置

# swagger static config
spring.mvc.static-path-pattern=/docs/**
# 项目静态资源的路径，会覆盖spring mvc默认的静态资源路径
spring.web.resources.static-locations=classpath:/docs

访问swagger ui

使用http://localhost:8080/我的项目路径/docs/index.html 访问swagger ui

到此，集成swagger文档结束，参考资料如下 github.com/swagger-api… github.com/swagger-api…

使用swagger生成jax-rs/jersey接口文档

背景

相关框架版本