search

apigee-127 / sway

A library that simplifies OpenAPI (fka Swagger) integrations/tooling.
MIT License
190 stars 92 forks source link

open API 3.0 spec support #128

Open leslie-wang opened 7 years ago

leslie-wang commented 7 years ago

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.

AlJohri commented 7 years ago

@whitlockjc I was wondering if there's any plans to start supporting the OpenAPI 3.0 spec. Thanks!

whitlockjc commented 7 years ago

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.

gooftroop commented 7 years ago

Any update on this now that it's GA?

whitlockjc commented 7 years ago

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.

nomadtechie commented 6 years ago

@whitlockjc is there anything you need help with to get 3.0 support out? Happy to contribute.

osher commented 6 years ago

@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.

amarzavery commented 6 years ago

@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?

osher commented 6 years ago

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

whitlockjc commented 6 years ago

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.

amarzavery commented 6 years ago

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 👍 .

whitlockjc commented 6 years ago

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.

osher commented 6 years ago

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 notifications@github.com 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 .

celalo commented 6 years ago

Any news on OAI v3.x support?

whitlockjc commented 6 years ago

Now that sway@v2.0.0 is released, OASv3.x support is the next major feature being worked on for sway.

celalo commented 6 years ago

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)

whitlockjc commented 6 years ago

I honestly have no idea how long it will take. Last I heard, OAS@v3.x 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. ;)

whitlockjc commented 6 years ago

Excuse my naivety...

philsturgeon commented 6 years ago

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

whitlockjc commented 6 years ago

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.

philsturgeon commented 6 years ago

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 notifications@github.com 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.

whitlockjc commented 6 years ago

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.

whitlockjc commented 6 years ago

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?

philsturgeon commented 6 years ago

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. :)

whitlockjc commented 6 years ago

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.

philsturgeon commented 6 years ago

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!

whitlockjc commented 6 years ago

I do like that idea. I'll reach out to @MikeRalphson to see what his thoughts are.

confuser commented 6 years ago

@whitlockjc Probably worth taking a look at https://github.com/exegesis-js/exegesis as well

DavidBiesack commented 6 years ago

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.

rahimimo commented 6 years ago

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 ?

whitlockjc commented 6 years ago

Can I say that master supports v3.x (WIP)?

DavidBiesack commented 5 years ago

I suggest not claiming that master supports v3 as a work in progress. I recommend creating a separate branch for the 3.0 work. At APIStrat, Jeremy asked about approaches for 3.0 support - I'd like to see sway support both "swagger: 2.0" and "openapi: 3.0.1" at the same time (same code base), rather that forking the tool. That's my opinion, tho. I don't recommend doing so via an implicit conversion (ala api-spec-converter or other), since error messages would become perturbed, perhaps pointing to paths such as /components/schemas (that do not appear in the 2.0 source) instead of /definitions

whitlockjc commented 5 years ago

I fixed the supported version in the README files. And thanks for the feedback. I like that approach too.

RomanHotsiy commented 5 years ago

Hey @whitlockjc, what is the current progress with this? I mean if I start using code from master, what is still missing?

Do you need any help?

whitlockjc commented 5 years ago

Progress is ongoing but not complete. Doing it alone means slower than ideal delivery. I'll try to get it out sooner.

osher commented 5 years ago

@whitlockjc - just to give you some kudos. I'm sorry I can't offer help ATM, by the time things got going - I sunk over my head. So - kudos. that's the least I can do!

whitlockjc commented 5 years ago

No worries. I've been dragging my feet due to no official JSON Schema for OAS@v3.x but I'm going to take a different approach starting today.

philsturgeon commented 5 years ago

@whitlockjc hey, is that new approach using the WIP? I don't want to sound like a dog with a bone but you could get a long way using that WIP and it shouldn't mess you up if they release an official metaschema during that time. If you've got a big healthy test suite then it'll aaaaall be fine. Probably. Right? :D

whitlockjc commented 5 years ago

The master branch is the WIP and it's where I'll be doing the work. I may end up creating a new OSS project for the types/validation of the OAS document, something that would address parts of #187, but I'm not 100% sure on that yet. Regardless, all of this is being done in master at this time.

MikeRalphson commented 5 years ago

I think @philsturgeon meant the WIP json schema(s).

whitlockjc commented 5 years ago

Ah yes. If I continue with the JSON Schema based approach, that's what I'll do. I'll make a decision here shortly.

philsturgeon commented 5 years ago

How's this coming along? Is there any of the tooling we can align on?

  1. stoplightio/json-ref-resolver has a few really handy local file, HTTP, or both $ref resolvers
  2. BiteBit/ajv-oai handles the validation by wrapping AJV with the OpenAPI v3.0 metaschema we discussed above (now merged!)

I know this tool has been around a long time but with these other tools marching forwards recently I feel like there is an opportunity to offload some maintenance burden to existing tools.

whitlockjc commented 5 years ago

Object model is complete, structural validation is complete. Semantic validation is almost complete. I will then do request/response validation and cut a release. The plan is to remove support for mock/sample generation for now. We can bring it back pretty easily, but the current approach brings in so much bulk that I don't want to stick with it if we don't have to.

Thanks for your patience.

whitlockjc commented 5 years ago

I'm glad you pointed me to stoplightio/json-ref-resolver, I didn't know they too were writing their own version of json-refs. I've reached out to better understand, I fear fragmentation for no real reason.

Ilham-Habibullin commented 5 years ago

Is there any updates for now?

whitlockjc commented 5 years ago

Sorry for the delay, but it's nearing completion. Structural document validation for 2.x and 3.x is working, semantic validation is almost done. All that's left then are a few APIs and request/response validation.

Ilham-Habibullin commented 5 years ago

I am specifically cared if OpenAPI v3.0 will bring feature with discriminator? Is there any chances that it will be supported in that coming release?

whitlockjc commented 5 years ago

discriminator is quite difficult to implement but it will be coming.

elecompte60 commented 4 years ago

Any updates on this or is this project dead?

whitlockjc commented 4 years ago

The project isn't dead, I just happen to be a one-man band so things happen much slower now that working on this isn't part of my day job.

philsturgeon commented 4 years ago

Maybe now is a good time to split it into a few smaller tools and see if we can find help from the community, getting folks to take ownership of those smaller tools. I'm starting to get together some resources on https://github.com/openapi-contrib, and having a simple validator over there would be massively useful. It would help a lot of people avoid needing to OAS+AJV for validation, which is a major pain point.