Should HTTP paths be shown in documentation?

[kubukoz]

HTTP is an implementation detail of the client/server, and the exact details of how a path gets rendered may be controlled by the protocol. This can happen arbitrarily and should probably not be supported explicitly (e.g. in the plugin interface).

From Smithy docs:

The resolved absolute URI of an operation is formed by combining the URI of the operation with the endpoint of the service. (that is, the host and any base URL of where the service is deployed). For example, given a service endpoint of https://example.com/v1 and an operation pattern of /myresource, the resolved absolute URI of the operation is https://example.com/v1/myresource.

Currently, Playground can't possibly be aware of a prefix being added by a protocol implementation (I know of at least one protocol that adds a path prefix based on the service's version and an optional operation trait for another segment). It could be shoehorned but probably not worth the effort.

I see the following options:

• keep doing it as it is (the paths are the same as in the spec, after all)
• remove HTTP trait support in the docs altogether

I'll pick one and implement it, probably after the next major release.

[kubukoz]

I'm starting to think protocol-specific help belongs to the plugin interface. Not sure long-term, but while only HTTP is supported this might be part of the SimpleHttpBuilder interface.