Создайте JSON, совместимый с jakarta swagger-ui, из исходного кода, используя maven

Здесь много похожих, но устаревших ответов. Недавно я переносил JavaEE -> Jakarta из старого проекта, когда у меня была такая возможность. Заметил, что все мои профили, связанные с swaggerм, перестали генерировать ожидаемый JSON/YAML.

Итак, как это работало раньше, так это то, что он использовал com.github.kongchen -> swagger-maven-plugin. Это сделает свою черную магию и сгенерирует json, который swagger-ui сможет легко нарисовать.

<plugin>
                    <groupId>com.github.kongchen</groupId>
                    <artifactId>swagger-maven-plugin</artifactId>
                    <version>${swagger.maven-plugin.version}</version>
                    <configuration>
                        <apiSources>
                            <apiSource>
                                <springmvc>false</springmvc>
                                <locations>
                                    <location>path.to.source</location>
                                </locations>
                                <schemes>
                                    <sheme>http</sheme>
                                </schemes>
                                <host>${swagger.api.host}</host>
                                <basePath>${swagger.api.basePath}</basePath>
                                <info>
                                    <title>Specs</title>
                                    <version>v1</version>
                                    <description>${swagger.api.header.description}</description>                                  
                                </info>                            
                                <templatePath>${apisource.templatePath}</templatePath>
                                <outputPath>${apisource.outputPath}</outputPath>
                                <swaggerDirectory>${apisource.swaggerDirectory}</swaggerDirectory>                                    
                            </apiSource>
                        </apiSources>
                    </configuration>
                    <executions>
                        <execution>
                            <phase>compile</phase>
                            <goals>
                                <goal>generate</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>

Сгенерированный JSON выглядел так:

    {
  "swagger" : "2.0",
  "info" : {
    "description" : "some description"
    "version" : "v1",
    "title" : "Title"
  },
  "host" : "localhost:8080",
  "basePath" : "/path/rest",
  "tags" : [ {
    "name" : "Service 1"
  }, {
    "name" : "Service 2"
    ...

Запросы, модели ответов и т. д. были сгенерированы нормально. В основном то, что я пытаюсь сделать, это иметь это, но совместимое с пространством имен Jakarta.

При переносе этого мне пришлось использовать другой плагин, так как kongchen не поддерживает jakarta.

Полученный профиль выглядит так

<profile>
        <id>new-generate-api-doc</id>
        <dependencies>
            <dependency>
                <groupId>io.swagger.core.v3</groupId>
                <artifactId>swagger-jaxrs2-jakarta</artifactId>
                <version>2.2.8</version>
            </dependency>
            <dependency>
                <groupId>org.webjars</groupId>
                <artifactId>swagger-ui</artifactId>
                <version>${swagger-ui.version}</version>
            </dependency>
            <dependency>
                <groupId>io.swagger.core.v3</groupId>
                <artifactId>swagger-integration-jakarta</artifactId>
                <version>2.2.8</version>
            </dependency>
            <dependency>
                <groupId>io.swagger.core.v3</groupId>
                <artifactId>swagger-annotations-jakarta</artifactId>
                <version>2.2.8</version>
            </dependency>

        </dependencies>
        <properties>
            <swagger.api.version>v1</swagger.api.version>
        </properties>
        <build>
            <plugins>
                <plugin>
                    <groupId>io.swagger.core.v3</groupId>
                    <artifactId>swagger-maven-plugin-jakarta</artifactId>
                    <version>2.2.8</version>

                    <configuration>
                        <outputFileName>swagger</outputFileName>
                        <outputPath>${apisource.swaggerDirectory}</outputPath>
                        <outputFormat>JSONANDYAML</outputFormat>
                        <resourcePackages>
                            <package>com.packages.source</package>
                        </resourcePackages>
                        <prettyPrint>true</prettyPrint>
                        <ignoredRoutes></ignoredRoutes>
                        <configurationFilePath>${apisource.swaggerDirectory}/openapi-configuration.yaml</configurationFilePath>
                    </configuration>
                    <executions>
                        <execution>
                            <phase>compile</phase>
                            <goals>
                                <goal>resolve</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>

Кто-то спросит, вот openapi-configuration.yaml:

resourcePackages:
- io.swagger.sample.resource
prettyPrint: true
cacheTTL: 0
openAPI:
  info:
    version: '1.0'
    title: API services specification
    description: Desc
    termsOfService: http://swagger.io/terms/

Но разрешенный JSON совсем не похож на тот, что был раньше. Нет тегов, нет ответов. Я явно делаю что-то очень неправильно.

Пример:

  {
  "openapi" : "3.0.1",
  "info" : {
    "title" : "services specification",
    "termsOfService" : "http://swagger.io/terms/",
    "version" : "1.0"
  },
  "paths" : {
    "/path/ann" : {
      "get" : {
        "operationId" : "getAnn",
        "parameters" : [ {
          "name" : "type",
          "in" : "query",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "orderby",
          "in" : "query",
          "schema" : {
            "type" : "string"
          }
        } ],
        **"responses" : {
          "default" : {
            "description" : "default response",
            "content" : {
              "application/json" : { }
            }
          }**
        }
      },
...
    "/api/v1/asset" : {
      "get" : {
        "operationId" : "getAllAssetsFromAssetIndex",
        "parameters" : [ {
          "name" : "regnumber",
          "in" : "query",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "vinnumber",
          "in" : "query",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "orderby",
          "in" : "query",
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "default" : {
            "description" : "default response",
            "content" : {
              "application/json" : { }
            }
          }
        }
      },

Обратите внимание на пустое поле «контент», без тегов и т. д. В этом случае код остался прежним, поэтому используются те же аннотации, что и раньше.

Запросы генерируются правильно, как и пространства имен. Но заметно, что я генерирую совершенно другой JSON, который затем отражается на дисплее.

Пример аннотаций сервиса:

    @Stateless
@Path(AssetServiceApiV1.BASE_URL)
@Api(value = "/" + AssetServiceApiV1.BASE_URL, tags = {AssetServiceApiV1.ASSET_SERVICE_TAG})
public class AssetServiceApiV1 extends RestServiceBaseApiV1 {

    public static final String BASE_URL = "api/v1/asset";
    public static final String ASSET_SERVICE_TAG = "Asset service";

    @GET
    @ApiOperation(
            httpMethod = "GET",
            value = "Get assets" + BEGIN_PARENS + APIFunctionalities.API_ASSET_READ + END_PARENS,
            notes = "Returns active assets with basic data. Various optional parameters are available.",
            response = AssetListV1Dto.class,
            responseContainer = OBJECT,
            produces = MediaType.APPLICATION_JSON,
            tags = {ASSET_SERVICE_TAG},
            code = 207
    )
    @Produces(MediaType.APPLICATION_JSON)
    public Response getAllAssetsFromAssetIndex(
            @ApiParam(value = "Registration number") @QueryParam("regnumber") String registrationNumber,
            @ApiParam(value = "...") @QueryParam("...") String ...,
            @ApiParam(value = "Available order by parameters are id, ..., ...") @QueryParam("orderby") String orderBy) {
...
    }

И вот объект ответа:

 @ApiModel(value = "Asset List Resource", description = "Asset list resource representation")
    public static class AssetListV1Dto {

        @ApiModelProperty(value = "List of assets", required = true)
        public List<AssetV1Dto> assetList;
        @ApiModelProperty(value = "List size", required = true)
        public int size;
...

    }

Я могу быть всего в нескольких милях от правильного решения и генерировать что-то совершенно другое. Все что угодно помогает. Кстати, здесь не используется Spring.

Но я абсолютно застрял, я понятия не имею, что использовать для создания json, подобного тому, который сгенерировал старый плагин, и я использовал swagger-editor в облаке для проверки вывода.