search

jhthorsen / json-validator

:cop: Validate data against a JSON schema
https://metacpan.org/release/JSON-Validator
56 stars 58 forks source link

Add support for post_process_refs in bundle() #175

Closed jhthorsen closed 4 years ago

jhthorsen commented 4 years ago

Summary

Allow $refs added by bundle() to be moved around. This is useful for bundled OpenAPI specifications.

I've not added any documentation, because I want to try it out in M::P::OpenAPI before I make this feature stable. (I might add EXPERIMENTAL documentation though)

Motivation

Want to make @HEM42 happy 😄

References

HEM42 commented 4 years ago

Hi,

I had a chance to look at this, are you sure its the right path, to do it in post processing ?

I believe it should not have been rewritten in the first place, where a ref like

#/components/responses/DefaultResponse

becomes

#/definitions/__components_responses_DefaultResponse

And then you have to rewrite it back into its original path again.

From what I saw in the generate_definitions_path branch, to me it looks more generalised

HEM42 commented 4 years ago

I have realised that the issue is not as much with the reference object; #/components/responses/DefaultResponse, you would know where to place this in the final rendering of the spec.

But when you have a reference to a relative file, then there might not be clear placement

When you have an OpenAPI v2 spec, you would properly place this under #/definitions/, which how its done in your current implementation

But if you have an OpenAPI v3 spec, there are several components objects to choose from under #/components/; responses, schemas and so on.

So unless you are able to see which valid components object you have from the file, then you have no way of knowing the correct path for it.

HEM42 commented 4 years ago

From what I saw in the generate_definitions_path branch, to me it looks more generalised

Have a look at my modifications to generate_definitions_path https://github.com/HEM42/json-validator/tree/generate_definitions_path_v2

Solves both the test, but also having deeper levels of references. Simpler for the user of J::V, and no further changes to Mojolicious::Plugin::OpenAPI to render a proper v3 spec.

However It will still place relative file references under #/definitions/, which maybe could be handled by using the ref_key in ->bundle(), and support ref_key input like ->bundle({ ref_key => '/components/schemas/' }). Which do realise is marked as deprecated.