Groups support for different model views about swagger-php HOT 33 CLOSED

I like the idea of exclusions and grouping this library exposes, I am going to shoot to add this in 0.5.0 sometime mid-January 2013.

from swagger-php.

Okay, that would be awesome!

from swagger-php.

Maybe in addition to #36, the property discoverer could also do an extra check by looking if a @ser\Groups annotation exists for the property, to decide if it must be included. This avoids the addition of a groups attribute to the swagger property, which causes documenting it twice and prone to error if not changed both in the future with the rename of a group.

from swagger-php.

edit: After more thought I do not want to have cross dependency development like this at the moment. I feel it opens up more potential BC concerns long-term. Having said that it is my I may change my mind as time goes by and the library matures a bit more and or more people request/develop the solution in a way that can exist without risking a BC breakage.

On Thu, Dec 13, 2012 at 10:12 AM, Pieter Vogelaar
[email protected]:

Maybe in addition to #36#36,
the property discoverer could also do an extra check by looking if a @SERhttps://github.com/SER\Groups
annotation exists for the property, to decide if it must be included. This
avoids the addiation of a groups attribute to the swagger property, which
causes documenting it twice and prone to error if not changed both in the
future with the rename of a group.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/39#issuecomment-11340386.

from swagger-php.

I have spent some time this weekend thinking about this; I think it can bring some very nice additions to the table. I wanted to share my thoughts and get more feedback before I begin any real work on it. I expect this to add a fair amount of complexity in the realm of models and will attempt to explain why.

In the following example I demonstrate a concept of views; the views would take the form of Model objects in the swagger documentation. Treated separately and individually. You would then have the ability to pick and choose properties based on the resource request. Consequently they would then be addressed via the responseType attribute in the Operation annotation.

<?php
namespace SwaggerTests\Fixtures2\Models;

/**
 */
use Swagger\Annotations as SWG;

/**
 * @SWG\Model(id="Facet", views="{facetAB, facetB, facetBC}")
 */
class Facet
{
    /**
     * @var string
     * @SWG\Property(name="prop1", type="string", views="{facetAB}")
     */
    public $prop1;
    /**
     * @var string some desc
     * @SWG\Property(views="{facetAB, facetB, facetBC}")
     */
    public $prop2;
    /**
     * @var Some_Object
     * @SWG\Property(views="{facetC, facetBC}")
     * @SWG\Exclude
     */
    public $prop3;
}

• Facet would return all properties with the exception of prop3 as it has an @Exclude annotations
• facetAB would contain properties prop1 and prop2
• facetB would contain properties prop2
• facetBC would contain properties prop2 and prop3
• facetC would contain property prop3

Please give me your thoughts and observations on this; it is still very much a thought in progress.

from swagger-php.

Along the lines of this discussion I submit this could/would be useful with scopes for operations and APIs as well to limit what is displayed based on the api-key scopes

from swagger-php.

Why would contain facetBC prop2 and prop3? I think only prop2 because it has the complete view string "facetBC"?

from swagger-php.

That was because I did not have a unit test for the comment and made a mistake, I have updated to correct that 🎱

from swagger-php.

Hahaha okay!

One more mistake I think: facetAB would contain properties prop1 and prop2, should be only prop1.

Also the two @swg\Property lines for prop1 should be one? @swg\Property(name="prop1", type="string", views="{facetAB}")

But besides that, I agree with your solution. It seems to fix the complete views/groups issue!

from swagger-php.

And this is why I prefer code review.

from swagger-php.

Is for the implementation of this solution still something required from Swagger UI? swagger-api/swagger-ui#116

from swagger-php.

Hi Robert, first of all I want to wish you a happy new year and the best wishes for 2013!

Have you found any time during the holidays to develop for this issue?

from swagger-php.

Any update on this issue?

from swagger-php.

Is this still planned to be picked up?

from swagger-php.

@pietervogelaar at this time I am swamped with work and unable to provide anytime on this once I find time to devote to it I will look into it in depth. Having said this I do not know when I will have this time.

from swagger-php.

Okay, I understand. Thanks for your reply!

Maybe I'm allowed to spend some time on this for my current project.

from swagger-php.

Is it still in the plans?

from swagger-php.

+1 for this feature.

from swagger-php.

👍

from swagger-php.

+1

from swagger-php.

Is this something that is still in the planning? If not, it could be something I could possibly contribute. I like this library but this is a possible deal breaker for using it in most API's I write that include serializer groups.

from swagger-php.

I've been following this group for quite some time now and have not seen anything indicating any plans @michellesanver but PRs are actively being merged so I would say "go for it". Maybe @bfanger can confirm.

from swagger-php.

+1

from swagger-php.

Sorry I haven't acted on this, I do not have time at the moment (expecting a baby in 3 - 4 weeks and it's taking all my energy). If someone else wants to do this, that'd be cool.

We found a workaround for now that works in our specific application (models are not always 100% correct at the moment but not the end of the world)

from swagger-php.

+1

from swagger-php.

+1

from swagger-php.

+1

from swagger-php.

+1

from swagger-php.

+1

from swagger-php.

+1

from swagger-php.

+1

from swagger-php.

A lot can be solved with $refs and model composition

Adding an additional grouping / splitting system will complicate using swagger-php.
The better the annotations map to the output, the simpler it is to write and debug those annotations.

Feel free to experiment and create a swagger-php plugin, i'll gladly add that to the related projects page

from swagger-php.

Nelmio\ApiDocBundle\Annotation\Model provides this kind of functionality using serialization groups @OA\Items(ref=@Model(type=Reward::class, groups={"full"})):

https://symfony.com/bundles/NelmioApiDocBundle/current/index.html#using-the-bundle

from swagger-php.