Tags for Endpoint and OpenAPI generation (#2716) #2930
Conversation
|
|
||
| import zio.http.codec.Doc | ||
|
|
||
| final case class Description(doc: Doc, tags: List[String]) { |
There was a problem hiding this comment.
I know this form is more convenient to work with as an implementor, but I feel like just adding another type of Doc, e.g. Doc.Tagged(doc, tag) will result in fewer breaking changes and a more ergonomic API for the developer, who ordinarily doesn't want tags. Then you can define Doc#tags to extract List[String] through recursion and otherwise use the same as you use this one.
There was a problem hiding this comment.
I get your point, but I am not sure how to handle tags in the middle of a docs ADT tree. Would we just ignore it, when rendering html/md? Do I get also deep nested tags when using recursion on any doc?
These thought lead me to this design
There was a problem hiding this comment.
Btw: Your design might be better, if not only endpoints but maybe data structures need to be tagged.
There was a problem hiding this comment.
I would collect them and render as <ul> / <li>.
So the tags are associated with the endpoint, and not specific items inside the endpoint?
There was a problem hiding this comment.
So the tags are associated with the endpoint, and not specific items inside the endpoint?
I am not sure. For OpenAPI that is the only usecase (afaik). But I think Smithy has tags also on items.
I'll do changes later, I'll be working today on some of the larger issues
987Nabil
force-pushed
the
tags-endpoint
branch
3 times, most recently
from
c6c7000 to
e470a62
Compare
|
@jdegoes please check again |
|
@987Nabil Shouldn't a tag have optional description and externalDocs per OpenAPI 3.0 spec? I was thinking something like |
|
|
||
| def tag(tag: String, tags: String*): Doc = self.tag(tag +: tags) | ||
|
|
||
| def tags: List[String] = self match { |
There was a problem hiding this comment.
Should there be a method that does recursive tag extraction??
| @@ -542,7 +542,7 @@ object OpenAPIGen { | |||
| def operation(endpoint: Endpoint[_, _, _, _, _]): OpenAPI.Operation = { | |||
| val maybeDoc = Some(endpoint.doc + pathDoc).filter(!_.isEmpty) | |||
| OpenAPI.Operation( | |||
| tags = Nil, | |||
| tags = endpoint.tags, | |||
There was a problem hiding this comment.
Should this use the recursive method for tag collection?
| def tag(tag: String, tags: String*): Doc = self.tag(tag +: tags) | ||
|
|
||
| def tags: List[String] = self match { | ||
| case Tagged(doc, tag) => doc.tags :+ tag |
There was a problem hiding this comment.
This is not stack-safe and will blow up on sufficiently nested Doc.
fixes #2716
/claim #2716