Parameter shorthand schema instead of type

[jegsar]

Given the example - (body) complicatedPet {Object} the pet {} seems to use the type property. Is there a way to have it use schema instead so it could be - (body) complicatedPet {Pet} the pet or - (body) complicatedPet {#/components/schemas/Pet} the pet?

[erunion]

Unfortunately not at the moment. We're open to accepting a pull request for it though if you'd like to take a stab at it.

[Khauri]

Hi, I would be willing to submit a PR for this. I think this could also potentially help with specifying arrays of items (unless there's a way to do this already that I'm missing?).

I'm imagining this would be simple enough to add to expandParam.

Would

- (body) complicatedPet {#/components/schemas/Pet} the pet

be the preferred syntax here? I would imagine that

- (body) complicatedPet {Pet} the pet

would be implemented by inferring the #/components/schemas prefix whenever there's no match for one of the open api data types (which I don't believe are formally defined in this codebase?) which would add some complexity, whereas the former, while verbose, only requires that you check the type starts with #.

Another option could be

- (body) complicatedPet {ref:Pet} the pet

# or
- (body) complicatedPet {schema:Pet} the pet

# or this combo
- (body) complicatedPet {ref:#/components/schemas/Pet} the pet

Which is easier to look at and is similar to the type:format syntax already used.

[erunion]

If you want to submit a PR, please do! This library already supports composing full OpenAPI schemas within docblocks so this would be nice to have for folks to use the shorthand style.

I like - (body) complicatedPet {schemas:Pet} the pet as that'll let you specify which component schema type it is.

[Khauri]

I did some work on this, just had some more questions.

I have it so that schemas:Pet would set a $ref for #/components/schemas/Pet, but in general any unrecognized datatype would route to some component definition so long as the format is non-empty. Is that what you were getting at by "let you specify which component schema type it is?"

I'm finding it a bit concerning doing this because if you accidentally mistype a recognized value, {strin:uuid}, it will assume strin is some component schema type and then either won't throw a validation error or the error it does throw will be somewhat unhelpful. I'm hesitant to go the other way around and try to recognize the fixed fields instead of the datatypes because according to the spec the Components Object is extensible.

Also with that format how should OpenAPI v2 be handled since it uses the #/definitions path usually? (I'm a noob with OpenAPI and never used v2 so if that's not the case then let me know).

Would this format:

- (body) complicatedPet {ref:schemas/Pet} the pet

be acceptable? The format property is a relative path. which will be prefixed with #/components/ in v3 and #/definitions in <= v2, or format can be an absolute path, meaning it starts with a # and no prefixing will occur allowing you to reference whatever you need to.

[erunion]

I'm happy with that format you suggested:

- (body) complicatedPet {ref:schemas/Pet} the pet

My main concern is that it should let you be able to load in schemas/* or requestBodies/* orparameters/* or whatever you'd like and that would work with that format above.

[erunion]

This is now supported in v5.2.0, Thanks @Khauri!