Combining static OpenAPI content with dynamic content from annotations is not working

dhoffer commented 1 week ago

Describe the bug

We are using Quarkus 3.12.3 with io.quarkus:quarkus-smallrye-openapi to generate OpenAPI document at both build time and runtime, we also use the swagger-ui properties to include the Swagger UI with our application.

We need to augment/combine some static OpenAPI content in a file with the above generated OpenAPI document. The docs say to place the static content in META-INF/openapi.yaml or to specify the custom location via additional-docs-directory, However neither of those approaches work, the static content is never combined with the generated OpenAPI results.

How can I enable the combining of content?

Expected behavior

We placed the static content at the location specified in the documentation. We were expecting it to work per the documentation.

Actual behavior

Generated output is just the dynamic content from annotations

How to Reproduce?

No response

Output of `uname -a` or `ver`

No response

Output of `java -version`

java 21.0.4 2024-07-16 LTS

Quarkus version or git rev

3.12.3

Build tool (ie. output of `mvnw --version` or `gradlew --version`)

Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae)

Additional information

No response

quarkus-bot[bot] commented 1 week ago

/cc @EricWittmann (openapi), @MikeEdgar (openapi), @phillip-kruger (openapi)

MikeEdgar commented 1 week ago

@dhoffer , just to confirm, you're placing the openapi.yaml in src/main/resources/META-INF correct?

dhoffer commented 1 week ago

Yes that is correct. I also tried using the additional-docs-directory property but that did not work either.

phillip-kruger commented 1 week ago

Can you provide a reproducer?

dhoffer commented 1 week ago

That will be difficult as our project is huge and non-post able. Do you have unit tests where you test this and it does work? Perhaps I could investigate your tests and see I am doing something wrong.

dhoffer commented 1 week ago

I just created a rest-json-quickstart sample app and added an openapi.yaml file and it is being ignored, it is ignored both at build time and runtime. We would want to specify the file location but this shows even the default location does not work.

rest-json-quickstart.zip

MikeEdgar commented 1 week ago

Thanks @dhoffer , I'll check it out.

MikeEdgar commented 1 week ago

@dhoffer , I see the problem. It's dealing with the static file itself having the wrong format. The openapi key should be the OAS version, like 3.0.3, and info, servers, security, and paths are top-level items - not nested under openapi.

Before:

openapi:
  info:
    version: 2.0
    title: Sample REST Quarkus Application Title 2
    description: 'Sample REST Quarkus Application Info 2'
    termsOfService: https://acme.com/useragreement.html
    contact:
      name: Test Contact Person
      email: test.person@acme.com
  servers:
    - url: https://api.acme.com
      description: Development & Test Server.
  security:
    - BasicAuth: [ ]
  paths:

After:

openapi: "3.0.3"
info:
  version: "2.0"
  title: Sample REST Quarkus Application Title 2
  description: 'Sample REST Quarkus Application Info 2'
  termsOfService: https://acme.com/useragreement.html
  contact:
    name: Test Contact Person
    email: test.person@acme.com
servers:
  - url: https://api.acme.com
    description: Development & Test Server.
security:
  - BasicAuth: [ ]
paths: []

dhoffer commented 1 week ago

@MikeEdgar Oh my bad, I did not realize there was a format change. We have been using this format for years with the Swagger jars and it works fine but I'm good with the switch. I just have a couple of follow-up questions.

I see that the static file content is last in priority, e.g. if I already set a value in smallrye-openapi config then that value is used. Is there a way to configure priority between static file, smallrye-openapi config & annotation scanning?
Could there be a warning during the build to alert the user that they are using an unsupported OpenAPI static file content?

MikeEdgar commented 6 days ago

@dhoffer , there is not currently a way to configure the priority. Probably the config would always take the highest priority, but perhaps there could be an option to specify an order for the other sources (including the OASReader which you are not using).

Similarly, a warning might make sense for unexpected properties in the static JSON/YAML.

Both of these would start as feature requests in smallrye-open-api.

phillip-kruger commented 4 days ago

Closing here. Please open issues in SmallRye for the warning and config (if needed)

quarkusio / quarkus