Linking to endpoints in Document

(Colleen Chan) #1


I’m writing pages in the Document Hub to explain the APIs that we have, and I’d like to link to specific API Endpoints that are in the .oas2 file. Is there any way to do this?

I’ve only seen that you can create a document hub page with page type of ‘OpenAPI’ which links to the entire modelling file.


(Taylor Barnett) #2

Hey Colleen,

It is technically possible, but there isn’t a nice UI for it like when referencing a whole OAS document. You have to go into the code view to do it. I can create an example for you.

(Taylor Barnett) #3

For example, I want to link to this endpoint in a subpage by itself:


Like thiis:


I would have to reference it with ./main.oas2.yml#/paths/~1todos/post


(Colleen Chan) #4


Thanks for that! That is very helpful!

Is there also a way to reference it as a link within a page? eg in the Markdown using Text… something like [API Endpoint Name](Path to the Specific Endpoint as a document page)??

Hope that makes sense…


1 Like
(Taylor Barnett) #5

In that case, I would treat it like an external link and link directly to it where ever it is in your Hub.

So for example, for one of our endpoints, I’d use:

[Build docs API endpoint](

(Colleen Chan) #6

Thanks for that!


1 Like
(Dbrebu) #7

Hi Taylor,

Could you please advise how to link to the Update Todo endpoint in your example, which points to /todos/{todoId} instead of todos? I have already tried using “./main.oas2.yml#/paths/~1todos/{todoId}/put” and “./main.oas2.yml#/paths/~1todos/~2{todoId}/put” based on your example but it does not work. I am imagining there is some sort of syntax error that I can’t figure out on my own.

Also, is there a way to reference the findPets endpoint under petstore.oas3?

Diana Brebu

(Taylor Barnett) #8

One small tweak:


Just a note, this is a little hacky way to do it, so it doesn’t have the best UX, but it should work.

For findPets, this should work:


1 Like
(Dbrebu) #9

I have tried both methods and they work just fine. However, none of these methods works for adding a reference to a model defined in a yml file in a Markdown file.

I have taken a look at the documentation for BigCommerce, and it looks like they have managed to do so. Is there any way you can also help with a solution for this?

(Taylor Barnett) #10

This was not done by direct referencing a model, like above with paths. That model you linked is in the OpenAPI document and they referenced the whole document.

I’m not sure if referencing models works in the same way as paths. I will look into this.

Is there a reason you don’t want to share all your models?

(Dbrebu) #11

Thank you, Taylor. I have changed the structure of my API documentation so as to be able to reference a whole OpenAPI document, and it looks good now.

(Taylor Barnett) #12

Great to hear @dbrebu!