$ref quotes while generating .yaml from java classes

[Vazhenston]

Hi,
I'm trying to generate open-api.yaml from java classes with using springdoc-openapi-maven-plugin 1.4 But, unfortunately, when I use $ref in @Schema annotation, it does not generate quotes, but it's very important for me.
I tried to use ", ', `. I noticed, that maybe problem is in using some symbols in the beginning of $ref. For ex. if I use .(dot), it does not generate quotes, but if I use ,(comma) , it does. I suppose, that problem is in parsing from .json to .yaml.

My profile for pom.xml

<profile>
            <id>swagger-generate</id>

            <build>
                <plugins>
                    <plugin>
                        <groupId>org.springframework.boot</groupId>
                        <artifactId>spring-boot-maven-plugin</artifactId>
                        <configuration>
                            <jvmArguments>-Dspring.application.admin.enabled=true -Dspring.profiles.active=localdev
                            </jvmArguments>
                        </configuration>
                        <executions>
                            <execution>
                                <goals>
                                    <goal>start</goal>
                                    <goal>stop</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>

                    <plugin>
                        <groupId>org.springdoc</groupId>
                        <artifactId>springdoc-openapi-maven-plugin</artifactId>
                        <version>${springdoc-openapi-maven-plugin.version}</version>
                        <executions>
                            <execution>
                                <id>integration-test</id>
                                <goals>
                                    <goal>generate</goal>
                                </goals>
                            </execution>
                        </executions>
                        <configuration>
                            <apiDocsUrl>http://localhost:8080/v3/api-docs.yaml</apiDocsUrl>
                            <outputDir>src/main/resources/swagger</outputDir>
                            <outputFileName>final_openapi.yaml</outputFileName>
                            <skip>false</skip>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        </profile>

My class' element sample:

@Schema(requiredMode = Schema.RequiredMode.NOT_REQUIRED,
            ref = "./common/common_openapi.yaml#/components/schemas/RefObject")
    private RefObject icon;

My result in open-api.yaml

        icon:
          $ref: ./common/common_openapi.yaml#/components/schemas/RefObject 

Thank you,
Best wishes

[bnasslahsen]

Not reproducible.
Feel free to provide a Minimal, Reproducible Example - with HelloController that reproduces the problem.

This ticket will be closed, but can be reopened if your provide the reproducible sample.

[Vazhenston]

I try on more time :D

I have this common_openapi.yaml

openapi: 3.0.1
info:
  title: title
  version: 0.0.1
tags:
- name: Example API operation
  description: basic example
paths:
  /example-path/xyz:
    get:  
      tags:
        - Example API operation
      summary: common objects usage example
      operationId: exampleOperationId
      parameters:
      - $ref: '#/components/parameters/HeaderAcceptLang'
      responses:
        "200":
          description: Successful call        
          content:
            application/json:
              schema: 
                type: string
        "404":
          $ref: '#/components/responses/ErrorResponse404'
components:
  parameters:
    HeaderAcceptLang:
      name: Accept-Language
      in: header
      schema:
        type: string
        default: en-US

  responses:
    ErrorResponse404:
      description: Not found

then i try to generate new_openapi.yaml of my project, but with references on components from common-openapi.yaml

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;

@RequestMapping(value = "example/api")
@Tag(name = "Hello API")
public interface HelloApi {

    @Operation(
            parameters = {
                    @Parameter(ref = "./common/common_openapi.yaml#/components/parameters/HeaderAcceptLang"),
            }
    )
    @GetMapping("/hello")
    ResponseEntity<ResponseObject> hello();
}

import io.swagger.v3.oas.annotations.media.Schema;

public class ResponseObject {
    @Schema(requiredMode = Schema.RequiredMode.NOT_REQUIRED)
    private String text;
}

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.servers.Server;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.List;

@Configuration
public class OpenAPIConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI().info(new Info()
                        .title("Example project")
                        .version("0.0.1"))
                .servers(List.of(
                        new Server().url("http://localhost:8080/api").description("localhost")));
    }
}

when i try to generate it with using springdoc-openapi-maven-plugin in pom.xml

<properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <maven.compiler.target>21</maven.compiler.target>
        <maven.compiler.source>21</maven.compiler.source>

        <java.version>21</java.version>

        <spring-cloud.version>2023.0.3</spring-cloud.version>
        <jackson-databind-nullable.version>0.2.6</jackson-databind-nullable.version>
        <springdoc-openapi-maven-plugin.version>1.4</springdoc-openapi-maven-plugin.version>
        <springdoc-openapi-version>2.6.0</springdoc-openapi-version>
        <maven-artifact.version>3.9.9</maven-artifact.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web-services</artifactId>
            <exclusions>
                <exclusion>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-starter-tomcat</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

        <!-- open-api -->
        <dependency>
            <groupId>org.openapitools</groupId>
            <artifactId>jackson-databind-nullable</artifactId>
            <version>${jackson-databind-nullable.version}</version>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>${springdoc-openapi-version}</version>
        </dependency>

        <!-- lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>

        <!-- tests -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- other -->
        <dependency>
            <groupId>org.apache.maven</groupId>
            <artifactId>maven-artifact</artifactId>
            <version>${maven-artifact.version}</version>
        </dependency>
    </dependencies>

    <profiles>
        <profile>
            <id>swagger-generate</id>

            <build>
                <plugins>
                    <plugin>
                        <groupId>org.springframework.boot</groupId>
                        <artifactId>spring-boot-maven-plugin</artifactId>
                        <configuration>
                            <jvmArguments>-Dspring.application.admin.enabled=true -Dspring.profiles.active=localdev
                            </jvmArguments>
                        </configuration>
                        <executions>
                            <execution>
                                <goals>
                                    <goal>start</goal>
                                    <goal>stop</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>

                    <plugin>
                        <groupId>org.springdoc</groupId>
                        <artifactId>springdoc-openapi-maven-plugin</artifactId>
                        <version>${springdoc-openapi-maven-plugin.version}</version>
                        <executions>
                            <execution>
                                <id>integration-test</id>
                                <goals>
                                    <goal>generate</goal>
                                </goals>
                            </execution>
                        </executions>
                        <configuration>
                            <apiDocsUrl>http://localhost:8080/v3/api-docs.yaml</apiDocsUrl>
                            <outputDir>src/main/resources/swagger</outputDir>
                            <outputFileName>new_openapi.yaml</outputFileName>
                            <skip>false</skip>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        </profile>
    </profiles>

I get this new_openapi.yaml

openapi: 3.0.1
info:
  title: Example project
  version: 0.0.1
servers:
- url: http://localhost:8080/api
  description: localhost
paths:
  /example/api/hello:
    get:
      tags:
      - Hello API
      operationId: hello
      parameters:
      - $ref: ./common/common_openapi.yaml#/components/parameters/HeaderAcceptLang
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ResponseObject"
components:
  schemas:
    ResponseObject:
      type: object

here is a structure of my project for openapis

as i wrote above

I tried to use ", ', `. I noticed, that maybe problem is in using some symbols in the beginning of $ref. For ex. if I use .(dot), it does not generate quotes, but if I use ,(comma) , it does. I suppose, that problem is in parsing from .json to .yaml.

[Vazhenston]

Not reproducible. Feel free to provide a Minimal, Reproducible Example - with HelloController that reproduces the problem.

This ticket will be closed, but can be reopened if your provide the reproducible sample.

if my new comment with more detailed description is sufficient, please, reopen the issue.

Thank you

[bnasslahsen]

@Vazhenston,

Add the link to a public github repo, where all the code is integrated in a reproducer project and share the link in the issue.

[Vazhenston]

@Vazhenston,

Add the link to a public github repo, where all the code is integrated in a reproducer project and share the link in the issue.

here it is

https://github.com/Vazhenston/QuotesMissingError