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]> 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] > <mailto:[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] >> <mailto:[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 >>> <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] >> <mailto:[email protected]>. >> For more options, visit https://groups.google.com/d/optout >> <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 > > <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] > <mailto:[email protected]>. > For more options, visit https://groups.google.com/d/optout > <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] > <mailto:[email protected]>. > For more options, visit https://groups.google.com/d/optout > <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.
