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. <http://www.strava.com/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.
