This repository has been archived by the owner on Sep 22, 2021. It is now read-only.
Add special formatting for CIDs and Multiaddrs #13
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Cid objects always serialize to JSON as `{"/": "<cid string>"}` (https://github.com/ipfs/go-cid/blob/078355866b1dda1658b5fdc5496ed7e25fdcf883/cid.go#L407-L415). There's no obvious way to detect what any type's serialization behavior might be, so we need a special case explicitly for CIDs here.
Also specially calls out Multiaddrs. It doesn't appear that we have any other interfaces or pointer types besides these two that wind up in response schemas. I don't know that string checking on the type is really the best way to do this, but it seemed expendient and avoids needing to depend on CID and Multiaddr packages and make sure they stay in sync with the version of IPFS we are working against.
There is also some discussion here (ipfs/kubo#5077) on whether this is the right formatting for CIDs. For now, I'm including it here because I heard plenty of complaints about the usefulness and accuracy of these docs from users. The output of this tool is preceived as documentation and not a spec, so I think it's right that it shows what IPFS actually *does,* not just what we think it *ought* to. (If we wanted this to be more like a spec, we need a way to annotate it for users to explain the difference between implementation and spec.)
License: MIT
Signed-off-by: Rob Brackett <rob@robbrackett.com>
Mr0grog
added a commit
to ipfs-inactive/docs
that referenced
this pull request
Jun 11, 2018
Uses docs generated via ipfs-inactive/http-api-docs#13, which are more accurate about response format and type.
Mr0grog
added a commit
to ipfs-inactive/docs
that referenced
this pull request
Jun 11, 2018
Uses docs generated via ipfs-inactive/http-api-docs#13, which are more accurate about response format and type. Licese: MIT Signed-off-by: Rob Brackett <rob@robbrackett.com>
|
I did something similar when I upgraded this to work with 0.4.18 |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
CID objects always serialize to JSON as
{"/": "<cid string>"}(https://github.com/ipfs/go-cid/blob/078355866b1dda1658b5fdc5496ed7e25fdcf883/cid.go#L407-L415). There's no obvious way to detect what any type's serialization behavior might be, so we need a special case explicitly for CIDs here.This also specially calls out Multiaddrs.
It doesn't appear that we have any other interfaces or pointer types besides CIDs and Multiaddrs that wind up in response schemas right now. I don't know that string checking on the type as I’m doing here is really the best way to do this, but it seemed expendient and avoids needing to depend on CID and Multiaddr packages and make sure they stay in sync with the version of IPFS we are working against. (If you have feedback on this, @Stebalien, I’d love to hear it — I’m no Go expert and certainly not familiar enough with the intricacies of GX to understand what makes the most sense.)
There is also some discussion here (ipfs/kubo#5077) on whether this is the right formatting for CIDs. For now, I think it makes sense to include the
{ "/":here because I heard plenty of complaints about the usefulness and accuracy of these docs from users. The output of this tool is preceived as documentation and not a spec, so I think it's right that it shows what IPFS actually does, not just what we think it ought to. (If we wanted this to be more like a spec, we need a way to annotate it for users to explain the difference between implementation and spec. A tool like this one that generates the doc would probably not be the right choice anyway, then.)