Move swagger documentation out of repository and split specification files

[DeRain]

Hello, actually I've done this work but I'm not sure how should I relate this to the plugin. If you could create repository under the Sylius organization based in mine - it would be fine.

Please, check my repo with the specification - it looks much better that one file solution. Also, i've fixed some validation errors for the specification and now it's fully compatible with swaggerhub and we have a option to provide a documentation in UI and run a mock server as well.

The repo (currently it generates a swagger.json, but it could be easily converted into yaml by the swaggerhub): https://github.com/DeRain/SyliusShopApiPlugin-Swagger

Swaggerhub: https://app.swaggerhub.com/apis/DeRain/sylius-shop_api/1.0.0

[Zales0123]

Hello Kirill and thank you very much for your effort! You did a wonderful job, indeed. To be honest, I think we need some time to discuss how we want to handle this issue. Sadly but truly, I think we can't keep documentation in the separate repository (we also abandon this idea for https://github.com/Sylius/Sylius some time ago), on the other hand we can't keep such advanced application in this repo, only for the documentation... However it would be a big shame to not appreciate your hard work on the documentation and to not use your code :) Let's keep this issue open and I think that in (I hope so) the nearest future we will take some decisions about it. Thank you one more time for you work!

[DeRain]

@Zales0123 Hello Mateusz and thank you for the response. Sure, ping me, if you will need help in any case with this. As an option - it could be distributed as an npm package with API testing as well using language agnosting framework Dredd (https://github.com/apiaryio/dredd). This tool takes swagger documentation as an input and applied automatic tests for an API according to swagger.

More info here https://blog.apisyouwonthate.com/keeping-documentation-honest-d9ab5351ddd4

So the basic idea is keep documentation and implementation separated as it helps to uncover outdated documentation and broken features.

Thank you for reading!

[lchrusciel]

Are you willing to give a try to set up dredd for this project? Or t least give it a try? I don't have any experience with it, but it would be an awesome feature to have it

[DeRain]

Currently, i'm working on the project based on Sylius and when i will have a chance I will setup Dredd for this project and then I think I will be able to adapt this for SyliusShopApiPlugin.

Thank you!

On Thu, Feb 1, 2018 at 1:17 PM, Łukasz Chruściel notifications@github.com wrote:

Are you willing to give a try to set up dredd for this project? Or t least give it a try? I don't have any experience with it, but it would be an awesome feature to have it

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/Sylius/SyliusShopApiPlugin/issues/251#issuecomment-362221030, or mute the thread https://github.com/notifications/unsubscribe-auth/AD0FzENiAxWeRsiBEca4pZSQLf2Q69cbks5tQY8cgaJpZM4RtD7n .

[mamazu]

Is there any update to this?

[lchrusciel]

no :(

[mamazu]

I will have a look at testing an API based on dredd this weekend because I will probably be using this in the future.

[mamazu]

Can't get it to work though.