Sylius
Move swagger documentation out of repository and split specification files
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
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!
@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!
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
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 [email protected] 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 .
I will have a look at testing an API based on dredd this weekend because I will probably be using this in the future.