Add docs for delimited path parameters #4079
Conversation
mitchldtn
changed the title
doc/endpoint/codecs.md
Outdated
| @@ -88,6 +88,89 @@ Different codec formats can be used in different contexts. When defining a path, | |||
| with the `TextPlain` media type can be used. However, for bodies, any media type is allowed. For example, the | |||
| input/output described by `jsonBody[T]` requires a json codec. | |||
|
|
|||
| ## Handling Delimited Path Parameters | |||
There was a problem hiding this comment.
Thanks for the proposal! I think I'd suggest moving it to a top-level page linked in the How To section. The "codec" section over here is more of a reference, and this describes a specific use-case
There was a problem hiding this comment.
I see the How To section references links to .scala files. To follow that same pattern I'm thinking I'll convert this to DelimitedPathParameterExample.scala and add code comments. Unless I'm missing something and I can just attach a .md
There was a problem hiding this comment.
Oh no, I meant a regular .md page. There are links to examples in the Examples section, but you should be able to add a link here: https://github.com/softwaremill/tapir/blob/master/doc/index.md?plain=1#L158 to the new page
There was a problem hiding this comment.
I wasn't too sure where it should be housed so I made a dir for how-tos and placed it in there. Let me know if I should change that or rename it.
doc/endpoint/codecs.md
Outdated
| ## Handling Delimited Path Parameters | ||
|
|
||
| Tapir allows you to handle complex path parameters, such as lists of custom types separated by delimiters (e.g., commas). | ||
| This can be achieved using Codec.delimited, which facilitates the serialization and deserialization of delimited lists |
There was a problem hiding this comment.
| This can be achieved using Codec.delimited, which facilitates the serialization and deserialization of delimited lists | |
| This can be achieved using `Codec.delimited`, which facilitates the serialization and deserialization of delimited lists |
doc/endpoint/codecs.md
Outdated
| ### 1. Define the Custom Type and Validator | ||
| Start by defining your custom type and the associated validator to enforce the desired pattern. | ||
|
|
||
| ```scala |
There was a problem hiding this comment.
this can probably be compilation-checked? you can do this by adding mdoc:compile-only and then running compileDocumentation from sbt to verify that everything works
There was a problem hiding this comment.
I ran that locally and got a success but needed to have all the code and imports together. I left mdoc:compile-only on the last code snippet but let me know if that should be removed.
|
@mitchldtn this looks good, I just adjusted the headers. Thanks! |
I saw #3877 pop up as a good first issue and wrote something up after reading the thread on the community forum.
Looking to do some contributing for the Hacktoberfest hackathon so if there are any other good first issues you guys would like some help on, I'm interested in contributing more than just some doc updates :)