sway
sway copied to clipboard
apigee-127
open API 3.0 spec support
OpenAPI will release version 3.0 at Feb 28, 2017. https://www.openapis.org/blog/2017/01/24/a-new-year-a-new-specification. It would be useful if this tool can support 3.0 as well.
@whitlockjc I was wondering if there's any plans to start supporting the OpenAPI 3.0 spec. Thanks!
We definitely plan on supporting it but I'm not 100% sure how to do it yet. In swagger-tools, a lot of heft and complexity comes from having a single library with support for multiple specs in it. I need to figure out how I want to support this.
Note: OpenAPI 3.0 is NOT GA yet but now that the Implementer's Draft is out, we should start working on this soon.
We're wrapping up the next sway release, bug/security fixes and enhancements. After that, 3.0 support will be our top priority. Sorry for the delay.
@whitlockjc is there anything you need help with to get 3.0 support out? Happy to contribute.
@whitlockjc - same question here. If it'd help if I join the effort - please contact me. theganyo has my private mail as I did some PRs for swagger-node-runner / bagpipes.
@whitlockjc - Any plans to move to 3.0 Open API spec? 3.0 is GA now. Folks have been asking for this since last year. I know you are super busy. We really love this library. It would be great if you can provide an approximate timeline on when will this be possible?
Guys, I suppose it's down to us to fork and get on with it. Or maybe start from scratch in pure ES7 porting the good stuff. Sadly, my current occupation does not involve swagger at all, but if it did - I't totally would have started by now. But my current position does not leave me much free time for efforts that do not promote the projects' main goals
I don’t see why threatening to fork is required when a PR, or PRs, would suffice. I’ve been the only active developer in this project from day one and like you, I’ve run into time conflicts lately. I’ve been trying to pick it back up (look at yesterday’s commits) but it’s not going to ever be as quick if I’m the only one doing it. 3.0 support will likely take some time and will likely require changing the architecture a bit but I’m more than happy to be involved. I will just need some help. If you think a fork is the best approach, by all means.
I don't think it was a threat of any kind. All of us love this repo and the work done by you over here. Since you are the main and only author of this repo, people are expecting a response from you on 3.0 support. @osher posted a comment on Jan 30 and I posted one 7 days ago asking for a timeline if any. This gives us the idea about where the project is heading with 3.0. It took slightly strong words from @osher for you to respond.
Anyways, I can completely understand the time constraints and you working on this project in extra time. More hands on this project would definitely help. I shall discuss this with my team to see what is the priority for 3.0 support and based on that would love to contribute in keeping this project open api 3.0 compliant.
Thank you once again for your response. Have a good day 👍 .
Well, let's make this happen. I'm putting in the time now and I'd love some help. My plan is to release 2.0.0 by EOW (barring any unexpected conflict) and then focusing on OAI v3.x support.
wow. I missed these mails. Anyway - no, I did not mean fork as in lets split into a new copy, but as fork - the first step in working on a PR.
Sorry for the confusion!
On Tue, Jun 5, 2018 at 7:29 PM, Jeremy Whitlock [email protected] wrote:
Well, let's make this happen. I'm putting in the time now and I'd love some help. My plan is to release 2.0.0 by EOW (barring any unexpected conflict) and then focusing on OAI v3.x support.
— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/apigee-127/sway/issues/128#issuecomment-394774673, or mute the thread https://github.com/notifications/unsubscribe-auth/AAxBHejzigL9ripF9thig36uSBeGVGLQks5t5rHUgaJpZM4LzEVu .
Now that [email protected] is released, OASv3.x support is the next major feature being worked on for sway.
Thank you very much for your immense efforts. I believe, OASv3.x support will need quite a lot of work but do you have a rough timeframe? Do you think it will take days, weeks or months? (I also presume, OASv3.x support will not land to swagger-tools project, since it's deprecated in favor of sway)
I honestly have no idea how long it will take. Last I heard, [email protected] doesn't even have a JSON Schema to use yet. So I need to figure out how that looks, what the delta is and go from there. I don't think the sway API itself will change much since the JavaScript objects we expose shouldn't change much and when it comes to the features available on them, they shouldn't change much either. Just know, this is me taking a guess and this could all be grossly inaccurate. ;)
They OpenAPI folks are still working on that, but this v3.0 metachema is usable despite being labeled as WIP. https://github.com/OAI/OpenAPI-Specification/pull/1270
It’s being used in a lot of tools like oas-kit: https://github.com/Mermade/oas-kit/tree/master/packages/oas-validator/schemas
Fair enough. I'm on the TSC and I know that it's a WIP but building on top of a WIP worries me a little, although I'm not against it.
Cool! Wasn’t pulling rank there just letting folks know in case they didn’t. 😬
I’ve been using oas-kit extensively at wework to validate all sorts of problems, and if there are edge cases the WIP doesn’t cover then I’ve not found them.
Put it this way: if you build a new version of sway presuming the WIP is close enough, and write everything to support v3, you can have that version as beta until the WIP is final. That’s going to avoid waiting for it to be done before building your new version, and make everything quicker for everyone without really adding an extra work to your plate.
-- Phil Sturgeon @philsturgeon
On Jul 25, 2018, at 12:46, Jeremy Whitlock [email protected] wrote:
Fair enough. I'm on the TSC and I know that it's a WIP but building on top of a WIP worries me a little, although I'm not against it.
— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.
Oh, I didn't take it that way. :) I wasn't pulling rank either but I can see how it could be taken that way.
Speaking of...any ideas on how you'd like sway to work with multiple versions of OAS? As we support multiple concurrent versions of the spec, you get to the point where the size of sway will increase. Also, since these JSON Schemas are JSON they are not typically minified during browser builds. I'm thinking of creating JSON object versions of them to remedy this. Thoughts?
Many tools implement an adaptor pattern approach, where a base class covers the most basic common functionality and inheritence covers the rest. You'd probably have distinct v2 and v3 base classes, and v3.1 could extend from v3.0, etc.
Or you can use mixins to cherry-pick functionality from a whole bunch of things.
This JSON Schema library does something similar: https://github.com/davishmcclurg/json_schemer/tree/master/lib/json_schemer/schema
Also, with oas-kit covering a lot of the same functionality as you, but already supporting v3.0 rather well, I'd see if there was any functionality could combine. Even using their resolver and/or walker would help you delete some code. There are quite a few Node modules floating around now, and it would be great to see things combinging so we can all work on building awesome tooling on top of that base layer of components, instead of all competing to build this same components and being stuck on step 1. :)
I'm all for collaboration. Being one of the first on the block for such things (sway started 2 years before oas-kit and was written to replace swagger-tools which was even older), I was surprised more people didn't contribute to my projects and would start their own. I've never pushed anyone away and I've been quite receptive to criticism and feedback. I'll stay in my lane for now and if people want to collaborate, I'd love to.
Excellent. Well, oas-kit is brand new but based on the logic from swagger2openapi, and of course exists because there are no v3.0-based tools out there. I wasn't suggesting ditching your thing because a new thing came along, but was suggesting you take a look at the multiple components they have to see if any of them can replace 2.0-only code you have there.
Another cool approach is to support v3.0 only, and use their swagger2openapi logic to convert in the background. That can really save some effort. :)
Either way, good luck with the v3.0-based tooling built on that WIP metaschema. I'm nudging the OpenAPI folks to get that finished up!
I do like that idea. I'll reach out to @MikeRalphson to see what his thoughts are.
@whitlockjc Probably worth taking a look at https://github.com/exegesis-js/exegesis as well
Glad to see progress and some momentum on 3.0. I would suggest, however, that the README.md not imply that master supports the latest (3.0) until it actually does.
I agree with @DavidBiesack I really do not know if now 3 is fully supported or not and what is the correct source to follow,. This issue thread or readme or ?
