Mark endpoints as private/hidden #433

Open
mohsen1 opened this Issue Aug 4, 2015 · 19 comments

Projects

None yet

6 participants

@mohsen1
Contributor
mohsen1 commented Aug 4, 2015

With Swagger inflector and Swagger-node it's now more common to have endpoints that we don't want to document but we want to have them in the spec for other uses. There should be a way to mark endpoints as private or hidden so they don't show up in the UIs but can be used with other tools.

@webron
Member
webron commented Aug 4, 2015

Need more that. What are some use cases where you don't want to document them, you do want them in the spec, but don't want them in the UI (which is sort of a contradiction on its own)?

Just trying to understand here.

@mohsen1
Contributor
mohsen1 commented Aug 4, 2015

Let's say you have an API that has some endpoints that you want only internal users know about it. In case swagger.{json,yaml} is exposed externally the private: true endpoints are stripped down by the server if user doesn't have "internal user security credentials" they won't see those endpoints .

This also can help swagger-node and swagger-inflector return 404 errors for secure endpoints when a request with invalid credential is coming in. GitHub API does this, if you don't have valid credentials you won't know about some secure endpoints at all.

@webron
Member
webron commented Aug 4, 2015

That's ACL on the Swagger definition which if we choose to add should be handled in a much different way than just adding a private/hidden property to an operation (there are other considerations as well, such as hiding tags and possibly others).

I believe we discussed it for 2.0, and not saying it should be dealt with in future releases, but the filtering may actually be the responsibility of the tools and not really part of the spec itself. I don't know the 'right' answer here.

@mohsen1
Contributor
mohsen1 commented Aug 5, 2015

Right, I think a simple boolean property will not be enough and there could be other scenarios more complex than internal user vs. public.

Swagger can use it's own security system to define what operation is available to view to which credential owner. By default all operations are available to public to see unless the showOnlyTo has the security that you have the credentials of.

For example:

swagger: '2.0'
info:
  version: 1.0.0
  title: Example
securityDefinitions:
  basicAuth:
    type: basic
paths:
  /:
    get:
      security:
        - basicAuth: []
      responses:
        '200':
          description: 'OK'
  /foo:
    get:
      x-showOnlyTo:
        - basicAuth
      security:
        - basicAuth: []
      responses:
        200:
          description: OK

In this Swagger, if I don't have basicAuth credentials I won't see /foo in the documents or swagger.json.

@webron
Member
webron commented Aug 5, 2015

I'd probably go with a different name, and possibly with a different kind of granularity, but yeah. At least now it can be solved with vendor extensions. We'll need to decide whether it should be part of the actual spec, but it's a legitimate overall use case.

@theganyo
theganyo commented Aug 5, 2015

Something like x-visibility or x-doc-visibility, maybe?

@webron
Member
webron commented Aug 5, 2015

Visibility is a result, but it's not necessarily the only issue. You may want to do something further like explicitly disallow execution based on specific credentials and not just hide it from the documentation. In this situation, the Swagger definition is not necessarily used for documentation purpose only anymore.

x-access, x-acl and so on may be more fitting. The value may not necessarily be a simple string or array either but a complex object (for different access levels and so on, or access groups and so on).

@theganyo
theganyo commented Aug 5, 2015

Isn't the "security" section for execution access control?

@webron
Member
webron commented Aug 5, 2015

The security refers to the requirements to execute the API, but it doesn't mean it should be hidden from the user. It just means the user needs to be aware of what security procedure is required before they an execute a request.

@theganyo
theganyo commented Aug 5, 2015

Right. What I'm saying is: The security section is already there for execution. We were talking about visibility. Why are you saying that we need an x-access to also control execution?

@webron
Member
webron commented Aug 5, 2015

And again the quote "There are only two hard things in Computer Science: cache invalidation and naming things." (Phil Karlton) comes to mind. I get what you're saying regarding the security section and the execution, but I see the restriction as somewhat different in the two cases.

The security is always exposed to the user, but the new property isn't (or is it?). The first is documenting the API, the second is meta documentation. I guess visibility could work, though to me it would mean something slightly different.

@theganyo
theganyo commented Aug 5, 2015

Well, I see several domains here:

  1. Expression of an API as documentation
  2. Authorization of access to sections of the API documentation
  3. Expression of an API as executable
  4. Authorization to execute an operation

My confusion is that I'm not sure which tags apply to which domains and how...

@webron
Member
webron commented Aug 6, 2015

I'm not sure I see the difference between 1 and 3, so would appreciate further explanation.

For 4. - security is meant to cover it.
For 2. - this is what I believe we're discussing right now. To be honest, I'm not sure this even belongs in the scope of the spec.

@mohsen1
Contributor
mohsen1 commented Aug 6, 2015

If ACL is not defined in the spec so the server can determine which endpoints to show programmatically the only alternative is to have multiple subsets of your spec served to different credential holders. Having multiple swagger specs for an API is not optimal IMO.

@webron
Member
webron commented Aug 6, 2015

It's not the only way. Nothing prohibits you from adding your own vendor extensions to perform it. In swagger-core we allow definition filtering based on information available from the code. There are a few ways to solve it. Not every vendor extension should make it into the spec eventually. It could also be a separate file describing it, as it is meta documentation.

For now I'm just throwing ideas around, no concrete opinion yet.

@fehguy
Contributor
fehguy commented Feb 17, 2016

See #569

@tomchristie

Alternative: Serve different variations of the schema depending on the authentication context. That'll allow you to present differing sets of information to different clients.

@gwicke gwicke added a commit to gwicke/hyperswitch that referenced this issue Aug 15, 2016
@gwicke gwicke Support hiding entry points with `x-hidden`
This patch adds a small, private extension that lets us hide private entry
points from the docs by adding an `x-hidden` boolean property at the method
level. This is occasionally useful for "boilerplate" entry points like /robots.txt.

There are discussions about more advanced ACL-based doc hiding at
OAI/OpenAPI-Specification#433, but those haven't
lead anywhere yet. This is a simple solution that will work in the meantime.
7c59c73
@gwicke gwicke added a commit to gwicke/hyperswitch that referenced this issue Aug 17, 2016
@gwicke gwicke Support hiding entry points with `x-hidden`
This patch adds a small, private extension that lets us hide private entry
points from the docs by adding an `x-hidden` boolean property at the method
level. This is occasionally useful for "boilerplate" entry points like /robots.txt.

There are discussions about more advanced ACL-based doc hiding at
OAI/OpenAPI-Specification#433, but those haven't
lead anywhere yet. This is a simple solution that will work in the meantime.
acee96b
@petermorlion

Came here looking for this possibility. I'm totally new to Swagger, but here's my two cents: I believe @webron 's idea on vendor extensions allows for the most flexibility. It would allow the server to decide not to show something based on who is looking (anonmyous, paying customer, premium customer,...), but also other options we can't think of, e.g. only/don't show it after a certain date, etc.

@fehguy
Contributor
fehguy commented Sep 8, 2016

Yes, this is done in several OSS tools, such as swagger-inflector and swagger-core. Probably best not in the spec, though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment