How to make it work with swagger.io petstore example. about create-client HOT 10 CLOSED

this generator works over API documentation in below formats
https://demo.api-platform.com/docs.jsonld
https://demo.api-platform.com/docs.json

Check above out versus your documentation

from create-client.

Thanks very much!

In fact the .json you supplied is working.

However it is not working with:
https://petstore.swagger.io/v2/swagger.json

Could you give me pointers why? I get the same errors with our generated .json files.
Is there comething special about https://demo.api-platform.com/docs.json

from create-client.

The (not helpful) error in question:
TypeError: Cannot read property 'properties' of undefined

Command used:
generate-api-platform-client --format swagger https://petstore.swagger.io/v2/swagger.json ./BUILD

Thank you very much for the help :)

from create-client.

The client-generator is based on api-doc-parser that parses documentation of API created by API-Platform.
If you want to use it with different kind of API look inside the parser and check what would you need to change

from create-client.

Unfortunately, I don't think patching api-doc-parser is enough. api-doc-parse already supports Swagger v2, but client-generator has some hardcoded conventions regarding the IDs that are specific to JSON-LD.
To fully support Swagger, this should be abstracted.

from create-client.

I managed to get api-doc-parser working by adding some conditionals.
So it was not really swagger 2.0 conform but it was pretty close as I can see it.
(ok to be honest I am not really sure if it such a hard specification the more I work with it the more differences I discover ;) - sadly openapi 3.0 is not a possibility at this point in this project - it seems much more standarized )
But of course as @dunglas said client-generator fails to generate the full spec cause it is tailored to api-platform.

Honestly I dont see why you guys coded it that way cause as I see swagger 2 support at least for api-doc-parse would have not been that hard - but I understand that you need to support your product.

Which I like btw. I am still trying to get my company to use api-platform.
I have gotten rudimentray reudx components generation to work and I hope it will be enough to convince my team to use the service.

Thanks for the support!!

from create-client.

I managed to get api-doc-parser working by adding some conditionals.
Great, could you open a PR on api-doc-parser with your change to make the lib more robust?

But of course as @dunglas said client-generator fails to generate the full spec cause it is tailored to api-platform.

Probably a bit, but it's especially tailored for the Hydra spec. api-doc-parser has been first designed for Hydra. Swagger support came very recently (and it's why it is not mature yet).

Honestly I dont see why you guys coded it that way cause as I see swagger 2 support at least for api-doc-parse would have not been that hard - but I understand that you need to support your product.

It's not the story behind this. Ofc we test with API Platform first, but a main goal has always been to support other implementations of Hydra, and now OpenAPI as well. Swagger support in api-doc-parser has been contributed recently by someone who is not a maintainer of API Platform (and it's great!). We would be very happy to merge any contribution improving Swagger support in both api-doc-parser and this repository.

Which I like btw. I am still trying to get my company to use api-platform.

Thanks!

Making this tool compatible with Swagger shouldn't been that hard. Hardcoded things are basically the id (should be easy to make more generic) and pagination (probably less easy, but still doable, and can be just disable as a first step).

from create-client.

I would be happy to file a PR of the result, but honestly at the moment I am still finding out what makes swagger 2.0 - 'officially' swagger 2.0.
(You know standards)
For example I have different results with your 2.0 examples, the one from swagger.io and the docs generated from our backend. :_D

This is probably one of the reasons why OpenAPI was created.

Sorry for the critisicm, I am just recently exploring that space and its a bit atrocious the more I find out about it.
(stupid example: one problem with api-doc-parser I had was an unexpected Uppercase/Lowercase issue aswell as a deprecated field that did throw an error when it was not present, while checking its presence - so I am trying finding out what is a faulty swagger 2.0 doc and what is expected behavior - I dont think our docs are .... valid )
As Soon as I feel more comfortable I will create a PR.

I also see now why api-platform needs the augmented JSON-LD version.
It just makes sense.
(Main reason why I lean towards using a Service, actually but... enterprise...).

I will continue the discussion in api-doc-parser then.

Thanks so much :)

from create-client.

There is an "official" Swagger validator tool, we use it to test that the generated file in API Platform Core is valid: https://github.com/api-platform/core/blob/master/.travis.yml#L54

Unfortunately, sometimes the Swagger petstore itself is not valid (according to the validator...).
Anyway, as the motto said: "Be liberal in what you accept, and strict in what you produce", so while core must produce a valid Swagger doc, it would always be a good move if api-doc-parser could accept even slightly invalid files, any enhancement making the parser more tolerant would worth it.

from create-client.

Then I will try to produce a defensive fix that will warn about potential problems maybe?

Yeah I noticed that the Validator did produce curious results.
(Your Examples are valid indeed!)

Thanks Again you will hear from me in api-doc-parser soon. :)

from create-client.