Undocumented properties

[chris48s]

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

• latest_stable_version (string)
• latest_version (string)
• configs (object)
• retirements (object)

appear in the API responses but not in the corresponding docs

[lpil]

This was also confusing me, thanks

[ericmj]

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]

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

[ericmj]

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

[Pi-Cla]

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]

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

[Pi-Cla]

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]

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

[Pi-Cla]

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