The OpenAPI Spec Leads to Errors using openapi-generator-cli

[juangamnik]

When using e.g. typescript-axios OpenAPI generator, the spec validator spills out an error:

Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
 | Error count: 1, Warning count: 0
Errors:
    -attribute paths.'/search/'(post).responses.200.content.'application/json'.schema.items is missing

    at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:620)
    at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:647)
    at org.openapitools.codegen.cmd.Generate.execute(Generate.java:479)
    at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
    at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)

If you ignore it with --skip-validate-spec option, the generated code cannot be compiled because an Array type (for the search api) is generated without type parameter.

I have a "corrected" version of the search api (in the openapi.yaml), which generates and compiles, but I am unsure, whether this is a valid solution (instead of using the "oneOf"-variant I copied the definition of the 200-result of /search/simple/:

958,960d957
<                   required:
<                   - "filename"
<                   - "result"
965,971c962,983
<                     result:
<                       oneOf:
<                         - type: string
<                         - type: number
<                         - type: array
<                         - type: object
<                         - type: boolean
---
>                     score:
>                       type: number
>                     matches:
>                       type: array
>                       items:
>                         type: object
>                         required:
>                         - "match"
>                         - "context"
>                         properties:
>                           match:
>                             type: object
>                             required:
>                             - "start"
>                             - "end"
>                             properties:
>                               start:
>                                 type: number
>                               end:
>                                 type: number
>                           context:
>                             type: string

[coddingtonbear]

I'm somewhat surprised that validation would fail given that we build https://coddingtonbear.github.io/obsidian-local-rest-api/ from our OpenAPI spec using OpenAPI tools, but, maybe? I'm not sure offhand if the spec you've presented here matches, and it might be some time before I will be able to find the time to double-check things. Maybe try running a few of the searches to see if it matches in all cases?

[juangamnik]

As soon as I have some searches to make I will test them and give feedback. In the meantime here you may find a test project with both variants (i.e., original OpenAPI yaml and my adapted version). Just call npm run generate-obsidian-client. It will fail. If you change in the package.json the generate command to use obsidian-rest-api-openapi.yaml instead, it does not complain anymore.

obsidian-client-ts.zip

[coddingtonbear]

I've taken a moment to validate our OpenAPI schema across a few different validators online and I'm afraid all confirm that our schema is valid as-is. I understand that that's not the answer you're looking for and I apologize for that, but right now I'm currently of the belief that maybe this is a limitation of the particular tool you're using.

This isn't the end of the conversation, though -- absolutely do feel free to start a discussion about this in the discussions tab or find somebody to work with you on putting together a PR correcting the problem if you can find one.

Cheers & good luck!

[juangamnik]

Did you download my example and try it out? That takes 2mins. The „particular tool“ is openapitools/openapi-generator-cli, which is an official openapi tool IIRC.

Can you please name/link me the validators? With this information I can file an issue at OpenAI.

[coddingtonbear]

I'm sorry to say that, no, I didn't take the time to try out what you've posted. I am sure you can understand that I've got a lot of competing priorities, and I have to be extremely judicious regarding what I agree to spend my time on open-source wise.
Although I understand that your use case is important to you, it's not currently in the scope of this project to accommodate every third-party tool; so just confirming that the provided spec is valid is as much time as I'm personally able to commit to this.

I know that that's not what you want to hear, and I'm sorry about that! You can definitely feel free to start a discussion via the Discussions tab to see if you can find folks to help you land on a solution to your problem if you're so inclined to do that; you might even find folks wiling to download your example above so they can help you narrow-in on a solution that works. If you do find a solution to your problem that does not negatively impact this project's use case for that file (generating accurate online documentation), absolutely do feel free to post a pull request, but please understand that the docs that that file generates are the important part.

In case you are still curious about what validations I tried; I tried the below, roughly in this order:

1. Opening the file in VSCode (which is really just essentially the same thing as...)
2. Validating it against this schema: https://github.com/OAI/OpenAPI-Specification/blob/main/schemas/v3.0/schema.json
3. Opening it in https://editor.swagger.io/
4. And validating it via https://apitools.dev/swagger-parser/online/

No validations failed in any case. It seems extremely likely that your particular tool requires that the YAML be somewhat more strict than the standard.

Cheers & good luck! I hope some other folks with a little more time are able to help you find a solution!