docs: add full schema link

[TC-MO]

Add full schema link to API docs introductory paragraph

[jancurn]

Wouldn't it be better to link https://github.com/apify/apify-docs/tree/master/apify-api/openapi instead of this strange page? People can find more in that directory. Also, please let's add JSON version

[B4nan]

It's the very same content, compiled into one file. I believe this is what anyone would use if they want to work with our schema.

I will add the JSON version tomorrow, again, it will be a single file. We can surely link to the source files if that makes some sense (but I am not sold on that really, who does that, what would be the use case?).

Thoughts @netmilk?

[jancurn]

Oh yeah, but still I think it's good to link the GitHub source code from which the actual API docs are generated. We do the same for all our docs pages. And who knows, maybe somebody will send a PR...

[netmilk]

The simplest convention in the OpenAPI community is is that the compiled openapi.yaml and openapi.json are in the root of the API URL space, serving as a single source of truth for the API itself. They are idelaly deployed together with the API service implementation and tested against it.

In our case:

https://api.apify.com/v2/openapi.json

If not possible, the proposed URL will do for now, because we don't do "API design first" and the openapi document is dependant on the API implementation, not vice versa. The openapi document will be discoverable through the link in the API Docs for now.

it's good to link the GitHub source code
People won't see the href= base URL unless they "copy as link it" and paste it somewhere. If we want to navigate people to the Docs Github repo to edit the openapi, we need to do a better job communicating the repo in the docs itself. Something along the lines of clickable source maps comes to my mind.

Relevant to this, there are more API discovery options to evaluate:
https://apisjson.org/
OAI/OpenAPI-Specification#1851
OAI/OpenAPI-Specification#724

[jancurn]

I like the convention, we should ideally do it that way.

But still, let's add those YAML/JSON links to the API docs text (so that you can find it by searching "openapi"), and also let's add that link also to the GitHub directory with the source code.

Let's not overcomplicate this, we're talking about 2 lines of text here

[B4nan]

Maybe we can have a redirect (or rewrite) from api.apify.com, but from the context of apify-docs repo I don't think we can do that.

Btw since you wanted the JSON variant too, I had to patch the plugin, so I could alter the Export label too. Do we really need this if I change the label to Download OpenAPI like this?

#1419

[TC-MO]

That makes more sense to me than to have a button & separate link within prose

[B4nan]

Btw I also changed the URL (as agreed with Adam) to http://docs.apify.com/api/openapi.yaml and http://docs.apify.com/api/openapi.json in that PR, so if we want to keep it in the description, we'll have to adjust that.