Mark endpoints as private/hidden

[mohsen1]

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]

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]

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]

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]

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]

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]

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

[webron]

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]

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

[webron]

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]

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]

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]

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]

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]

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.