Add OperationId and Tags to identify and group operations, respectively

[Acentelles]

Documentation for endpoints in the type declaration:

• OperationId is an optional unique string used to identify an operation. If provided, these IDs must be unique among all operations described in your API.
• Tags are used to group operations logically by resources or any other qualifier.

Both OperationId and Tags are needed for different HasSwagger instances:

instance (KnownSymbol desc, HasSwagger api) => HasSwagger (OperationId desc :> api) where
  toSwagger _ =
    Servant.toSwagger (Proxy :: Proxy api)
      & Swagger.allOperations . Swagger.operationId ?~ Text.pack (symbolVal (Proxy :: Proxy desc))

instance (SymbolVals tags, HasSwagger api) => HasSwagger (Tags tags :> api) where
  toSwagger _ =
    Servant.toSwagger (Proxy :: Proxy api)
      & Swagger.allOperations . Swagger.tags .~ (Set.fromList $ Text.pack <$> symbolVals (Proxy :: Proxy tags))

[phadej]

This is IMHO too specific, and I cannot see why those should be in servant.

@alpmestan opinions?

[Acentelles]

In the same way paths may have an optional short summary and a longer description for documentation purposes, they may also have an operation id and tags associated (see https://swagger.io/docs/specification/paths-and-operations/). Otherwise, some documentation tools don't display documentation nicely.

Servant already has Description and Summary.

[alpmestan]

I'd be tempted to say "why not". (it's a bit hard to draw a line that delimits things that we want in the core packages and things that should live in satellite packages. But in this case, description/summary seem close to operationid/tags in spirit.)

[alpmestan]

I'm not against including these combinators. But if we decide to land this, we will need to include those in the comprehensive API that we use for our tests, and make sure to include a test or two to guarantee that this doesn't break in the future. A mention or two somewhere in our docs would be great as well. :-)

[centromere]

tempted to say "why not"

What are the consequences of being wrong?

[phadej]

Yes is permanent, no is temporary. Removing (or redoing in non trivial way) things is very difficult. That said, I don’t like Description combinator we have either. Writing longer pieces of text is not convinient in promoted Symbols. One option is to change Summary and Docs into more extensible single Docs combinator, and use Fold* like approach with them. Then it should be possible for server, client interpretations, etc to just ignore it, and servant-swagger to add own subcombinators it cares about.

…

On 19 Dec 2019, at 9.36, Alex Wied ***@***.***> wrote: tempted to say "why not" What are the consequences of being wrong? — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

[sorki]

There is a similar Tag in servant-util along with couple of instances. Also standalone OperationId PR at #1378