search

hexpm / specifications

Specifications for using and implementing Hex protocols
48 stars 26 forks source link

Undocumented properties #31

Open chris48s opened 3 years ago

chris48s commented 3 years ago

Hi. I spotted that there are some properties in the Hex API responses that aren't in the documentation:

appear in the API responses but not in the corresponding docs

lpil commented 3 years ago

This was also confusing me, thanks

ericmj commented 3 years ago

We need a way to automatically generate and update the documentation based on https://github.com/hexpm/hexpm. If anyone has proposals or experience doing this, please share.

lpil commented 1 year ago

Seeing as there's no progress here would PRs updating the apib file be accepted?

ericmj commented 1 year ago

We would very gladly accept PRs to update the API specifications.

Pi-Cla commented 5 months ago

We need a way to automatically generate and update the documentation based on https://github.com/hexpm/hexpm. If anyone has proposals or experience doing this, please share.

What I wonder is if this is even possible right now. At a minimum what I would want in API documentation is: 1) The path I would need to make a request to 2) The request method and payload I would need to send 3) What this particular combination of path and request method actually does 4) The responses and status codes I could get

As a newbie to this API I don't know if there is a automate-able way to find any of this information from https://github.com/hexpm/hexpm.

I can figure out 1-3 based on https://github.com/hexpm/hex/blob/main/lib/mix/tasks/ and https://github.com/hexpm/hex/tree/main/lib/hex/api

What I currently do is for example go to https://github.com/hexpm/hex/blob/main/lib/mix/tasks/hex.owner.ex which explains what each function below does and then I see which API function it is calling and track it down there https://github.com/hexpm/hex/blob/main/lib/hex/api/release.ex. The API function tells me the path and what method + payload I need to send.

I have no idea how to determine 4 in a reliable way. Afaik there are all sorts of places in https://github.com/hexpm/hexpm which could sent a response so there is not just one location I could look at to see where all possible responses could be...

Pi-Cla commented 5 months ago

And the awkward thing is that I am determining 1-3 based solely on code from hex not even hex.pm :(

Pi-Cla commented 5 months ago

This also applies to getting a human to update the apiary. Where should a human look to confirm or correct the information in the apiary? Is there a single place where a human could see all of the possible responses for an API call?

I think there needs to at least be a document made that says where a human could verify the API docs here.

chris48s commented 5 months ago

I'd assume they're generated from the API Blueprint in https://github.com/hexpm/specifications/blob/main/apiary.apib

Pi-Cla commented 5 months ago

I'd assume they're generated from the API Blueprint in https://github.com/hexpm/specifications/blob/main/apiary.apib

I think the API blueprint itself is handwritten though given no one updating it in 6 years