Adding Data Models inside API Documentations

api-documentation

#1

How do I add Data Model documentation to my APIs inside postman?

One of the examples I see for good documentation reference is https://apidocs.imgur.com/ So for example, under Account, they have " Response Model: Account " which links back to their API docs at https://api.imgur.com/models/account

I am not really sure how to do this inside Postman or whether it can even be done?

Feels like a common use case but couldn’t find any documentation around how to do this properly in Postman.


#2

Hey KS! Everything you need to know about creating documentation using Postman can be found on our Learning Center. I recommend checking out the following two articles to get started:


#3

Hey @john-paul
Thanks for the reply!

OK - So I get the part about the Markdown and being able to add rich content.

My question was regarding - https://s3.amazonaws.com/postman-static-getpostman-com/postman-docs/anchor-id.png

In that Image - I get that I can add markdown for “Response Model: Album” and add a hyperlink to it similar to Imgur. Can it be done directly inside Postman?

[Edit: Or rather - is there a “best practice” that is used to do this? Right now, I am using a folder and adding model documentation in that description. It feels like a hack so I am not sure if I missed something obvious.]

(Even the Imgur site links it to an older section of their documentation at https://api.imgur.com/models/gallery_image)


#4

No problem, @kshitizshankar. :slight_smile:

I believe I see what you mean – yes, this can be done directly inside Postman!

There’s another thread which goes over this in pretty good detail. Basically, if you click on a folder or request on your docs page, then check your address bar, you’ll see the unique tag for it at the end of the URL.

Example:
https://documenter.getpostman.com/view/5293839/Rztms92o#c892f021-30c4-4595-9e9d-c877b4423352

You can then link directly to this id anywhere else in the page using the following Markdown syntax:

[Link Text](#abcdef01-2345-6789-abcd-ef0123456789)

You can also do the same thing with the Introduction section: [Intro Sections](#intro)

Check out the following docs site for a ton more examples on using Markdown in Postman:


#5

Yeah I know how to add the hyperlink to the documentation to refer to other sections on the page. My key issue is - How to write the specs of the Data Model inside postman. It’s not exactly a part of a request so is there a way to add that??

The Imgur API Docs are using a separate site for that and then linking it back to the Postman documentation. I need a way to be able to add all this documentation around the Database Schema etc. for a resource.

Another example of it would be https://developers.trello.com/reference/#card-object

I doubt I’d be able to create well structured markdown for all this data - So - How do I do this in Postman?


#6

@kshitizshankar Gotcha. Sorry, I didn’t read your initial comment closely enough.

You can depict data models using example responses, or Markdown tables.

Segment’s documentation page is a fantastic example.


#7

Oh perfect! That helps a LOT!

Thanks :slight_smile:


#8

Awesome! Glad I could help. :slight_smile: