Adding Data Models inside API Documentations

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.

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:

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)

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:

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:

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?

@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.

Oh perfect! That helps a LOT!

Thanks :slight_smile:

Awesome! Glad I could help. :slight_smile:

Since my OpenAPI doc has schemas for the responses defined for a path (e.g. in paths.{sompath}.post.responses.200.content.application/json.schema), is there some way to get one or more of those schemas to generate documentation for the response body? Or do I need to dupe it in a table?

The accepted answer here seems to be to duplicate models in Markdown tables. I looked at Segment’s documentation per your recommendation and found that their tables are out of sync with their models (at minimum, I observed a misspelling). There’s got to be a way to generate docs from the response schemas, right?