Thanks Tony, will investigate. Dave
On Monday, April 17, 2017 at 7:09:35 PM UTC-4, tony tam wrote: > > Hi Dave, with the changes coming in the 3.0 spec, you can define schemas > for the input payloads and expect that inputs will have to match a schema > to “get in”. So that is a good thing and seems to satisfy your first > question. > > From the docs point of view, we are currently working on how that will > look in the swagger-ui. Most likely there will be an area where a payload > can be described, and different schemas / models to see that your model > matches against them. And in this case, this doesn’t have much to do with > the HTTP method, although we have updated the spec to make it clear that > methods which do not define behavior (like GET) for request payloads may > not have request payloads… > > If you’re looking for pure RPC-style modeling tools, you might look at > what is there for modeling gRPC since it’s fairly modern and popular. That > is for describing protobufs but the concept is the same. > > On Apr 17, 2017, at 1:34 PM, Dave Merrill <[email protected] <javascript:>> > wrote: > > Actually, all of our inputs and outputs are quite strong typed, not in the > Java actually-is-an-instance-of sense, since some access is across the web, > but they are all named types, most of which have some sort of validation > (regex, enum, array-of-this-type-of-object, etc). > > How do you guess the changes you're talking about will affect the API docs > UI? > > None of those enhancements are likely to do away with the REST verbs, HTTP > return codes, etc, right? > > Not to drag you off topic, but are you aware of any tools for designing, > documenting, and testing APIs along the lines I'm talking about? > > On Mon, Apr 17, 2017 at 2:09 PM, tony tam <[email protected] <javascript:>> > wrote: > >> Hi Dave, you are describing a fairly typical RPC-style API, and it’s >> difficult to model those call with any REST framework. >> >> You can, however, look at what is being done in the 3.0 version of the >> specification behind Swagger (now called the Open API Specification) and >> see that we are supporting different schemas for the input. You can >> *always* say that the “input is an object” and let the user (either >> client or server) figure it out. >> >> If you can constrain the types of objects being passed to the system, you >> can start using polymorphism via discriminator in the current 2.0 >> specification. Then you can say that you’re passing a “Fruit” and that >> fruit may be of type “Apple”, “Pair”, etc. It sounds like that my be not >> usable for what you’re looking to do. In the 3.0 spec, you can say that >> the input is “oneOf” a fixed set of types, which could be “Fruit, >> Automobile, Furniture, or plain Object” (for example) which does expand the >> options for inputs. Again, it is intended to be a somewhat constrained >> set, which is what allows the tooling to be useful. >> >> >> On Apr 17, 2017, at 11:05 AM, Dave Merrill <[email protected] >> <javascript:>> wrote: >> >> Thanks for getting back Tony. >> >> A bit more context: An app I work on has a largely HTML/JS/Ajax front >> end, but also supports server-side customization, where our back-end >> methods can be called by native customer code, no HTTP involved. >> Additionally, the parts that are called via HTTP/Ajax aren't REST at all, >> they're simple GET or POST requests to a common front controller URL, with >> the object and method to be called and any parameters in URL or form >> variables. >> >> From what I've seen of Swagger and API Blueprint, both require a) >> different URI endpoints for different target objects, b) different HTTP >> verbs for the canonical REST/CRUD actions, and c) REST-specific HTTP >> response codes. Am I right about that? If so, as you say, it's kind of a >> square peg/round hole problem. The editing environment, mocks, generated >> stubs, really the whole ecosystem, would all fight you if you tried to use >> them in that context. >> >> If that's the case, are you aware of any API design tools or description >> languages that might be a better fit? >> >> Thanks again very much for your time and thoughts, >> Dave >> >> >> On Monday, April 17, 2017 at 1:36:46 PM UTC-4, tony tam wrote: >>> >>> Hi Dave, you sort of can, but it’s going a bit against the grain. The >>> ecosystem is more intended for rest-like APIs, although being “strictly” or >>> even “proper” restful is certainly not a requirement. >>> >>> On Apr 17, 2017, at 5:00 AM, Dave Merrill wrote: >>> >>> Hi folks, I'm brand new to Swagger, just looking at its capabilities. >>> >>> Is it possible to use Swagger to document APIs that don't use REST, just >>> standard component.someMethod(someArg="foo", [...]) calls? >>> >>> Thanks. >>> >>> -- >>> You received this message because you are subscribed to the Google >>> Groups "Swagger" group. >>> To unsubscribe from this group and stop receiving emails from it, send >>> an email to [email protected]. >>> For more options, visit https://groups.google.com/d/optout. >>> >>> >>> >> -- >> You received this message because you are subscribed to the Google Groups >> "Swagger" group. >> To unsubscribe from this group and stop receiving emails from it, send an >> email to [email protected] <javascript:> >> . >> For more options, visit https://groups.google.com/d/optout. >> >> >> >> -- >> You received this message because you are subscribed to a topic in the >> Google Groups "Swagger" group. >> To unsubscribe from this topic, visit >> https://groups.google.com/d/topic/swagger-swaggersocket/Sl1bMWSKqYU/unsubscribe >> . >> To unsubscribe from this group and all its topics, send an email to >> [email protected] <javascript:>. >> For more options, visit https://groups.google.com/d/optout. >> > > > -- > You received this message because you are subscribed to the Google Groups > "Swagger" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected] <javascript:>. > For more options, visit https://groups.google.com/d/optout. > > > -- You received this message because you are subscribed to the Google Groups "Swagger" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. For more options, visit https://groups.google.com/d/optout.
