Ajv $ref problem

I found that the ajv can’t resolve

$ref:#/components/schemas/someSchema

which is supposed to be supported by openapi 3. After I studied some of the source code, I found that foal didn’t adding the whole openapi.json schema when initializing the ajv instance, but only validate against a part of the schema.

[LoicPoullain]

Possible implementations of the solution of the issue 2

The description below is a summary of the in-depth study that took into account performance considerations, the difficulty/feasability, the amount of work required and the maintainability and testability of the new code.

It is mostly a help for me to implement the feature

Implementation 1: the framework replaces the values of the $ref keyword in the hooks

Idea: replace the $ref value with another link to the schema to get rid of the #.

Cons:

• Traversing all validation schemas to replace the $ref value will probably cause performance issues.
• Schemas need to be registered manually to the AJV instance.
• Errors returned by the validation hook might be inconsistent with the OpenAPI document.
• Component schemas can reference other schemas with #, so this won’t work.

Implementation 2: use one global AJV schema so that # works.

Idea: build a global AJV schema which contains the OpenAPI component schemas.

Cons:

• AJV is deeply embedded in the core of the framework.
• OpenAPI and JSON schema are slightly different. This solution does not deal with it.
• Only a part of the application may be described by an OpenAPI document (ex: /api is but the pages routes are not).
• Several openAPI documents may co-exist in the same application.
• This implementation would require an initialization step to build the global schema from all the hooks and we would have to manage generated IDs. Supporting hook initialization would introduce certain complexity which I wouldn’t go with.

Implementation 3 (the one chosen): use local AJV schemas

Idea: keep a local schema in each hook which is compiled the first time the hook is executed. Add the document component schemas to the hook schema.

I don’t think this implementation would lead to peformance issues but we’ll have to check.

Pros: the cons of implementation 2

The last difficulty that we have to face is to get the component schemas of the OpenAPI document which the controller belongs to.

For this, an OpenApiService can be added to register the OpenApi specifications(s) with their controller instances (then the hook will be able to know which API it belongs to).

Currently the component schemas are only discovered for the first time at run time when requesting /openapi.json (it calls createOpenApiDocument in the SwaggerController).

One way to do this (not chosen)

A boot method in the controller that creates the specs when launching the application and register them into the service.

Cons:

• It is a bit hacky and complexifies the internal OpenAPI code which already complex.
• It only works with one OpenAPI document because the hook cannot know which API it belongs to.

The other (right) way (chosen)

Refactor the core code so that the documents (known by @ApiInfo) and the app routes are built at the same moment. At this moment the document are registered in the service.

Pros:

• Reduce the amount of code that lives in the framework core. The tree searches are currently dupplicated.
• Several OpenAPI documents can be supported.

Cons:

• Refactorisation of the framework core (sensitive part of the framework).
• Special case for generating a spec for a shell script.

[LoicPoullain]

Feature added in v2