OpenApiSchemaProperty support array of objects

[ChrisB85]

OpenApiSchemaProperty support array of objects

[cnizzardini]

Am I understanding the main goal is to return a custom array of objects?

[cnizzardini]

I'd have to probably dig into this one for a bit. Off the top of my head your immediate workarounds (if this indeed is not possible) are:

Events: https://github.com/cnizzardini/cakephp-swagger-bake#event-system
CustomSchemaInterface: https://github.com/cnizzardini/cakephp-swagger-bake/blob/master/docs/attributes.md#schema

[ChrisB85]

Am I understanding the main goal is to return a custom array of objects?

Yes exactly. I think it's the only thing missing to get full flexibility in documenting custom code. I'll see if I can do something with Events and CustomSchemaInterface.

Thanks!

[cnizzardini]

@ChrisB85 did this solve your needs?

[ChrisB85]

Unfortunately not. I tried to use events to modify the Swagger object but at some point I realized that It's just bad (to complicated) solution if I need to document many endpoints that way.

[cnizzardini]

Yeah I agree, I think your use-case is reasonable. I'll note this as a feature request.

[cnizzardini]

I think I've actually had this need in one of my applications, but out of sheer laziness have just left that portion of the schema not documented well.

[cnizzardini]

I'm curious @ChrisB85, if for a more reasonable short-term work around, can you use a mixture of $ref and OpenApiSchemaProperty. Something like this:

OpenAPI Schema:

#[OpenApiSchema(visibility: OpenApiSchema::VISIBLE_ALWAYS)]
class ArticleProperties extends DataTransferObject
{
    #[OpenApiSchemaProperty(name: 'id', type: 'string', format: 'int32', example: '3214')]
    public string $id;
    #[OpenApiSchemaProperty(name: 'name', type: 'string', example: 'Some name')]
    public string $name;
}

Controller:

#[OpenApiResponse(schemaType: 'array' ,ref: '#/components/schemas/ArticlesCollection')]
public function findArticles()
{
    // controller action code...
}

OpenAPI YAML:

components:
  schemas:
    ArticlesCollection:
      properties:
                  data:
                    items:
                      type: object
                      allOf:
                        - $ref: '#/components/schemas/ArticleProperties'
                    type: array

I think something like that may be possible. The idea being, document the object in your DTO, use OpenAPI YAML to document that its part of collection and then reference the YAML ref in your controller action.

[ChrisB85]

Thank you very much, I will try it :)

[ChrisB85]

Sorry for a delay, today I finally had some time to use your sugesstion. Unfortunatelly the ArticleProperties schema is not included into swagger.json so I get result like:

I think I need some clever way to include it.

[cnizzardini]

Ah this makes sense, I think its only adding schemas when there is an associated route. You can try adding this attribute and setting visibility, but I am not sure it will work. We are in slightly uncharted territory:

https://github.com/cnizzardini/cakephp-swagger-bake/blob/master/docs/attributes.md#openapischema