For any feature requests for the spec, you’re welcome to file a ticket at https://github.com/OAI/OpenAPI-Specification/.
From: <[email protected]> on behalf of Julien Silland <[email protected]> Reply-To: "[email protected]" <[email protected]> Date: Monday, July 31, 2017 at 11:09 To: "[email protected]" <[email protected]> Subject: Re: Inheritance and extension of API definitions Thanks Ron for your answer — this is a little disappointing but good to have our intuition confirmed. It'd be great if such use cases were supported in the future. In a perfect world, we'd version our API differently but this decision is well behind us at this point. I suspect the same is true for a number of API publishers out there. Beyond the public/private use case we are facing, implementing something along the lines of API inheritance/extension would enable fun/meaningful things: - extend public APIs, e.g. publish an API that replicates another one and adds additional endpoints or tunes the behavior of a specific endpoint - help with API versioning — it you could reuse large chunks of a previous version and selectively alter/deprecate certain endpoints. On your suggestion to filter out the specification when it is served — it's an interesting approach but I'm not entirely sure how workable that will be for us: our plan includes publishing the public spec to a public Github repo. I think I might try to develop some lightweight tooling of our own to do what we want here. Cheers, -Julien On Fri, Jul 28, 2017 at 6:37 PM, Ron Ratovsky <[email protected]> wrote: Hi Julien, The spec doesn’t quite support that. What it does support is referencing specific paths, and then theoretically you can add additional operations on top of that to the path. In practice, I’m not sure too many tools would support adding the additional operations, though the paths referencing should work. Depending on how you develop and build your API, you might be able to take a different approach. You can have everything in one file, and add some vendor extensions. You can write a very minimal app that will serve the spec with some form of authorization, and filter out the internal operations based on the extensions. From: <[email protected]> on behalf of Julien Silland <[email protected]> Reply-To: "[email protected]" <[email protected]> Date: Friday, July 28, 2017 at 15:59 To: Swagger <[email protected]> Subject: Inheritance and extension of API definitions Hello, My company runs an API that we surface to three distinct audiences: third party developers, partners and first party clients. What this segmentation means in practice is that depending on the nature of the clients, a given endpoint might be available to you or not, and it if is available, the response might be more or less rich. We are just getting around to completing the Swagger specification of our public API and eager to publish that. We also have a goal to consume a Swagger spec to generate clients and documentation for partners and internal customers. For confidentiality reasons, we'd prefer keeping the internal endpoints and payloads out of the public definition. Swagger comes out of the box with support for inheriting models and we're thinking of taking advantage of that to formalize responses returned by non-public endpoints: { "InternalFoo": { "allOf": [ { "$ref": "foo.json#/PublicFoo" }, { "properties": { … } ] } } What I'm trying to see is whether we could apply the same approach for extending the public API with partner and internal endpoints — ideally, we'd keep maintaining the external Swagger spec as is and the internal one would "inherit" from it and automatically benefit from additions to it, all the while accommodating the redefinition of certain response types and the addition of certain endpoints. At a fundamental level, what I'm trying to accomplish is: swagger-internal.json { "$ref": "swagger.json", "paths": { "/foo/{id}": { "get": { "responses": { "200": { "schema": { "$ref": "internal-foo.json#/InternalFoo" }}}}}} }, Is such a thing supported at all by the tooling? Is there a different model we could follow to accomplish this? Thanks, -Julien -- 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/xkn9tcx8tcM/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. -- Move at a regular pace and fix things STRAVA Stand With Us. -- 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.
