API documentation

🙋 Help
,
1

Hi. I am trying to convince my team to leave Swagger and use a pro Postman plan, however I seem to be missing some key features here, so please tell me if I missed them in the documentation.

  1. How can I document requests which take JSON as input? I see that instead of providing raw JSON, I can do the same in form-data. Are those two options equivalent when we are talking about the actual data that arrived at the server?
  2. Is there an option to set a parameter type, so that user knows whether to provide a string/int/float…?
  3. Can sample requests be ran in browser without actually having Postman? I know I can copy cURL request to terminal, but our users don’t know that.
  4. How can I document the URL parameter - i.e. api/users/{id}?

Thanks

2

Just like swagger Postman supports the use of openapi.

If your team uses openapi to swagger you can import those openapi files to postman to generate your docs/apis.

  1. You can define a request of type object and define the object
    https://swagger.io/docs/specification/describing-request-body/

  2. You can set data types
    https://swagger.io/docs/specification/data-models/data-types/

  3. No idea on this, never tried this functionality

  4. Same way

3

Thanks for the answer. Can you define objects and data types within Postman though, without using OpenAPI, or using it, but through Postman UI?

4

Not to my knowledge no.