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