Is SmartDocs susceptible to the same limitation that OpenAPI has with operation overloading?

Not applicable

Is SmartDocs susceptible to the same limitation that OpenAPI has with operation overloading? Refer to OpenAPI issue #146 for details.

For example, an API has two operations:

POST /to/some/collection

Content-Type: application/vnd.example.com.aaa+json

and

POST /to/some/collection

Content-Type: application/vnd.example.com.bbb+json

to overload the endpoint with different resource representations in the request body (the same would be for GET and Accept headers). Another example is the GitHub APIs which use application/vnd.github media types.

Open API 2.0 can't express this - one can only specify one model schema for the request body. Can SmartDocs do this? (We're just starting out with Apigee and have not gotten to the point of defining our API proxies or importing an Open API doc.). This might be a Developer Portal question...

thanks

0 3 116
3 REPLIES 3

Not applicable

While this can't be expressed in OpenAPI/Swagger, it *can* be expressed in WADL. Since SmartDocs was built with WADL support, you should be able to do it. This is possible because SmartDocs was originally built with a proprietary internal model.

However, the next generation of SmartDocs is moving toward OpenAPI as its internal representation, so operation overloading such as you demonstrate here is not future-proof.

@Daniel Johnson's answer is a good one. Also, it's worth noting that path overloading is an area of consideration for the next iteration of the OpenAPI Spec. I'd suggest participating in that thread, @David.Biesack, except that you started it. 🙂

Not applicable

yes, it's a pretty important topic for us.... and many others. I'm participating on the OpenAPI TDC on this and other topics, thanks. I'll look at the WADL - we may be able to convert our Swagger to WADL, then import that. But I hope Apigee won't remove this flexibility -- maybe wait for OAS 3.0 before dropping WADL support.