Body parameter descriptions

[Sebaroni]

Is there an existing request for this feature?

• [X] I have searched the existing issues for this feature request

Is your feature request related to a problem?

Hello! I’m porting OAS3 specs to Postman collections, but I don’t see the tables with the request body parameter descriptions in the documentation section. I was hoping Postman would render those automatically.

Those tables are nested under requestBody in the OAS yaml file.

For example: `requestBody: description: This API is used to ... content: application/json: schema: minItems: 1 uniqueItems: true type: array items: required:

• call_date
• call_identifier
• file_name
• unit_identifier type: object properties: call_identifier: minLength: 1 type: string description: record identifier. example: 0242ac130004`

Describe the solution you'd like

I'd like Postman to automatically render the tables with POST body parameter descriptions.

Describe alternatives you've considered

I'd like to avoid having to enter them manually using markdown.

Additional context

No response

[gerhardvr-finclude]

I 2nd this feature request. We go through great pains designing our APIs using OpenAPI YAML format and then generating the Postman collection and documentation off that. In the API spec our schema specifications contains descriptions but all that is shown in the Postman API document is the example request body.

We are using Postman specifically for its documentation capabilities and the fact that the documentation is always in sync with the API spec and collection. Therefore, to expect that the token information should be captured in the description of the endpoint makes no sense and is dangerous. It is too easy for the documentation to go out of sync with the schemas in the spec and it is too easy to make typing mistakes.

What is needed is that the schema is translated into the documentation. This should be quite easy to do since the schema is structured. For example, for the schema pasted below I would like to see something in the documenation that shows at least:

Token	Required	Type	Description
id_token	Yes	String	The id_token provided in the authentication call.
req_session_id	No	String	Global unique identifier for the session used.
req_device_id	No	String	The unique identifier for the device used in the transaction.
req_transaction_id	Yes	String	The unique transaction of the requester.
req_date_time	No	String	The date time stamp of the request.

  requestBody:
    description: 'Do an electricity meter lookup'
    content:
      application/json:
        schema:
          title: Lookup utility meter number detail
          description: Reguest the detail of a meter number
          type: object
          required:
          - id_token
          - req_transaction_id
          - parameters
          properties:
            id_token:
              description: The id_token provided in the authentication call.
              type: string
            req_session_id:
              description: Global unique identifier for the session used.
              type: string
            req_device_id:
              description: The unique identifier for the device used in the transaction.
              type: string
              maxLength: 255
            req_transaction_id:
              description: The unique transaction of the requester.
              type: string
              maxLength: 255
            req_date_time:
              description: The date time stamp of the request.
              type: string
              format: date-time

[5thdimensional]

Thank you for your request. This is something we've been very interested in as well, and your comment helps validate this need.

I appreciate your insight, and encourage you to keep those ideas coming!

[gerhardvr-finclude]

Not sure whether I have to log a new feature request but this is very closely related. I noticed that when I update the description field of the Openapi spec doc (highest level) I noticed that the validation does not even pick up that anything changed and therfore the change is never incorporated into the collection document at all. It has to be manually updated into the collection document.

On Wed, Aug 25, 2021, 20:38 Steven Baxter @.***> wrote:

Thank you for your request. This is something we've been very interested in as well, and your comment helps validate this need.

I appreciate your insight, and encourage you to keep those ideas coming!

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/postmanlabs/postman-app-support/issues/10231#issuecomment-905779311, or unsubscribe https://github.com/notifications/unsubscribe-auth/ASWJCTVWTHMUBGW7KYLGYR3T6U2ARANCNFSM5CM2JZ5Q . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email .

--  https://www.finclude.net https://www.finclude.net/ | e:  @. @.>

[kwolfy]

This is really missing in postman. When are you planning to implement? Our company has signed up for your paid plan, but unfortunately, due to the lack of a normal description of the body in documentation, we are forced to use other solutions like "redoc" for documentation

[Raja-Simha]

@gerhardvr-finclude @Sebaroni @kwolfy Could you guys briefly explain how your team expects to use documentation to develop and manage your internal and public APIs (if applicable) - from Open API definition to eventual API consumption. This will really help us understand your team's workflows better.

We are currently designing a solution to this problem and would like validate it. Thanks for your inputs as always.

[gerhardvr-finclude]

Hi Raja, On a whole, Postman already does 90% of what I require from the document management side of things. There are however a number of crucial missing features.  To start of I’ll give an high level overview of how I use Postman to design and manage the API and documentation. The API specification document is first written as part of the design process. We make use of YAML because it allows for better/easier documenting inside the YAML document than JSON does, and it allows for comments. An important part of this process is documenting the API using the “description” tags. We make heavily use of mark-up to make the document more readable.To further enhance the documentation, we typically also make use of the description tags when defining the response body schemas and the request body schemas      requestBody:        description: ''        content:          application/json:            schema:              title: Transaction Object List Request              required:              - id_token              - req_transaction_id              description: Retreive a list that contains the available transaction                objects.              type: object              properties:                id_token:                  description: The id_token provided in the authentication call.                  type: string                req_session_id:                  description: The unique session id of the requester.                  type: stringWe then use this API specification to automatically build a collectionWhenever anything in the documentation of the API needs to change, we update it in the API definition document, instead of editing the documentation via the document editor accessible from the collection. The idea is that the API Definition doc is the golden source of information. I should be able to send it to someone else and they should be able to regenerate the collection and the full API documentation. Current shortcomingsWhile the above sounds idealistic, I believe it is achievable in an ideal world, however, in practice it is not. The biggest issue I face is when I update the description fields in the API definition, Postman does not pick up that it has changed. Here is an example:I’ve update the description in the API definition document to now contain the words “Blah, blah” and then saved it but the collection documentation doesn’t show the update. I have to now edit the collection document manually. This is a guaranteed way for the collection document and the API definition doc to go out of sync.    The documentation is almost useless when it comes to the specification of the endpoint request and response bodies. We take time to fully specify the schema in the API definition, including descriptions but NONE of this is shown in the documentation. Being shown an example of the request body is absolutely worthless if all the important information such as required fields, type of the files and size/length of the field is not also shown.  From: RajaSent: Thursday, 21 October 2021 08:26To: postmanlabs/postman-app-supportCc: gerhardvr-finclude; MentionSubject: Re: [postmanlabs/postman-app-support] Body parameter descriptions ***@***.*** @Sebaroni @kwolfy Could you guys briefly explain how your team expects to use documentation to develop and manage your internal and public APIs (if applicable) - from Open API definition to eventual API consumption. This will really help us understand your team's workflows better.We are currently designing a solution to this problem and would like validate it. Thanks for your inputs as always.—You are receiving this because you were mentioned.Reply to this email directly, view it on GitHub, or unsubscribe.Triage notifications on the go with GitHub Mobile for iOS or Android.    https://www.finclude.net | ***@***.***

[gerhardvr-finclude]

Hi, Please ignore the below mail set moments ago. It was sent in error. I am still busy compiling the final email. Regards Gerhard  From: Gerhard van RensburgSent: Thursday, 21 October 2021 19:00To: postmanlabs/postman-app-support; postmanlabs/postman-app-supportCc: MentionSubject: RE: [postmanlabs/postman-app-support] Body parameter descriptions (#10231) Hi Raja, On a whole, Postman already does 90% of what I require from the document management side of things. There are however a number of crucial missing features.  To start of I’ll give an high level overview of how I use Postman to design and manage the API and documentation. The API specification document is first written as part of the design process. We make use of YAML because it allows for better/easier documenting inside the YAML document than JSON does, and it allows for comments. An important part of this process is documenting the API using the “description” tags. We make heavily use of mark-up to make the document more readable.To further enhance the documentation, we typically also make use of the description tags when defining the response body schemas and the request body schemas      requestBody:        description: ''        content:          application/json:            schema:              title: Transaction Object List Request              required:              - id_token              - req_transaction_id              description: Retreive a list that contains the available transaction                objects.              type: object              properties:                id_token:                  description: The id_token provided in the authentication call.                  type: string                req_session_id:                  description: The unique session id of the requester.                  type: stringWe then use this API specification to automatically build a collectionWhenever anything in the documentation of the API needs to change, we update it in the API definition document, instead of editing the documentation via the document editor accessible from the collection. The idea is that the API Definition doc is the golden source of information. I should be able to send it to someone else and they should be able to regenerate the collection and the full API documentation. Current shortcomingsWhile the above sounds idealistic, I believe it is achievable in an ideal world, however, in practice it is not. The biggest issue I face is when I update the description fields in the API definition, Postman does not pick up that it has changed. Here is an example:I’ve update the description in the API definition document to now contain the words “Blah, blah” and then saved it but the collection documentation doesn’t show the update. I have to now edit the collection document manually. This is a guaranteed way for the collection document and the API definition doc to go out of sync.    The documentation is almost useless when it comes to the specification of the endpoint request and response bodies. We take time to fully specify the schema in the API definition, including descriptions but NONE of this is shown in the documentation. Being shown an example of the request body is absolutely worthless if all the important information such as required fields, type of the files and size/length of the field is not also shown.  From: RajaSent: Thursday, 21 October 2021 08:26To: postmanlabs/postman-app-supportCc: gerhardvr-finclude; MentionSubject: Re: [postmanlabs/postman-app-support] Body parameter descriptions ***@***.*** @Sebaroni @kwolfy Could you guys briefly explain how your team expects to use documentation to develop and manage your internal and public APIs (if applicable) - from Open API definition to eventual API consumption. This will really help us understand your team's workflows better.We are currently designing a solution to this problem and would like validate it. Thanks for your inputs as always.—You are receiving this because you were mentioned.Reply to this email directly, view it on GitHub, or unsubscribe.Triage notifications on the go with GitHub Mobile for iOS or Android.     https://www.finclude.net | ***@***.***

[gerhardvr-finclude]

Hi Raja, On a whole, Postman already does 90% of what I require from the document management side of things. There are however a number of crucial missing features.  To start of I’ll give an high level overview of how I use Postman to design and manage the API and documentation and then my view of what it lacks. Unfortunately there is a LOT of information in this email and I’m sure it will be at times a bit confusing. If it will help, I will be happy to attend a video call to discuss and further clarify. The API specification document is first written as part of the design process. We make use of YAML because it allows for better/easier documenting inside the YAML document than JSON does, and it allows for comments. An important part of this process is documenting the API using the “description” tags. We make heavily use of mark-up to make the document more readable.To further enhance the documentation, we typically also make use of the description tags when defining the response body schemas and the request body schemas      requestBody:        description: ''        content:          application/json:            schema:              title: Transaction Object List Request              required:              - id_token              - req_transaction_id              description: Retreive a list that contains the available transaction                objects.              type: object              properties:                id_token:                  description: The id_token provided in the authentication call.                  type: string                req_session_id:                  description: The unique session id of the requester.                  type: stringWe then use this API specification to automatically build a collectionWhenever anything in the documentation of the API needs to change, we update it in the API definition document, instead of editing the documentation via the document editor accessible from the collection. The idea is that the API Definition doc is the golden source of information. I should be able to send it to someone else and they should be able to regenerate the collection and the full API documentation. Current shortcomingsWhile the above sounds idealistic, I believe it is achievable in an ideal world, however, in practice it is not. The biggest issue I face is when I update the description fields in the API definition, Postman does not pick up that it has changed. Here is an example:I’ve update the description in the API definition document to now contain the words “Blah, blah” and then saved it but the collection documentation doesn’t show the update. I have to now edit the collection document manually. This is a guaranteed way for the collection document and the API definition doc to go out of sync.    The documentation is almost useless when it comes to the specification of the endpoint request and response bodies. We take time to fully specify the schema in the API definition, including descriptions but NONE of this is shown in the documentation. Being shown an example of the request body is absolutely worthless if all the important information such as required fields, type of the files and size/length of the field is not also shown. We publish our Postman docs to the web but because of this shortcoming, we are forced to also send our YAML API definition doc to prospective clients so that they can use that to get the complete schema specifications.Compare this from Postmanwith this from one of the many examples I can pull from the APIs I work with daily.  Examples from other API document systems which I believe to be much better  3) I make heavily use of variables in my Postman collections with fairly complex Pre-request scripts and Tests to automate a create deal of collection testing. This in itself works very well. The problem is that when comparing the API definition with the collection, Postman picks up “Issues found” where none exists.. This is caused by using variables in the collection for values that are not defined in the schema as a string. This is hugely problematic because we attempt to always make sure that our API definition is 100% in sync with our collection.Below is the body definition but as can be seen in the API definition schema, api_tx_object_id is defined as an integer. Because of this Postman “finds” issues and then suggest replacing the whole body of the collection endpoint. BTW If api_tx_object_id was defined in the schema as being a string, and the variable in the collection body was quoted, Postman would not have raised an issue.   4) AS mentioned before, we rely heavily on the description fields in the API def doc. It is without doubt much easier to edit the collection documentation via die document editor than in the API definition editor. And while the API def can be used to create a collection with all the description tag values in the API def doc being shown in the newly created collection documentation, it is unfortunate that subsequent edits on the collection document are not reflected back into the API def doc. Below I edited the collection doc but as can be seen, I will have to manually add the same directly to the API def doc since it does not reflect there after saving the change to the collection doc.   5) This is not necessarily a lack of Postman but rather a limitation of OpenAPI YAML or my knowledge. Currently I lump everything relevant to the API as a whole, into the info.description section of the YAML API def doc. Within this Introduction section we put information regarding versioning, authentication methods, getting started, environments, error codes, glossary, etc. As you may imagine, this becomes very cumbersome. It would be a great help to be able to structure this a lot better. Regards Gerhard From: RajaSent: Thursday, 21 October 2021 08:26To: postmanlabs/postman-app-supportCc: gerhardvr-finclude; MentionSubject: Re: [postmanlabs/postman-app-support] Body parameter descriptions ***@***.*** @Sebaroni @kwolfy Could you guys briefly explain how your team expects to use documentation to develop and manage your internal and public APIs (if applicable) - from Open API definition to eventual API consumption. This will really help us understand your team's workflows better.We are currently designing a solution to this problem and would like validate it. Thanks for your inputs as always.—You are receiving this because you were mentioned.Reply to this email directly, view it on GitHub, or unsubscribe.Triage notifications on the go with GitHub Mobile for iOS or Android.     https://www.finclude.net | ***@***.***

[kago-dk]

@Raja-Simha If you look at what Stoplight (https://elements-demo.stoplight.io/#/operations/get-todos), Redoc (http://redocly.github.io/redoc/#operation/getUserByName) and Readme (https://developer.pagerduty.com/api-reference/b3A6Mjc0ODExMw-get-raw-data-single-incident) are doing, then it is challenging that Postman is not able to expose the datatype and description automatically in the Postman documentation (based on the OpenAPI spec) for the end consumer and keep it up-to-date, when changes happen to the specification.

Similar to @kwolfy we are, as paying customers, looking into stopping utilizing Postman for documentation because of these shortcomings and lack of improvements in the documentation component of Postman in general.

[Raja-Simha]

@kago-dk and @gerhardvr-finclude thanks for the detailed explanations. We are planning to provide a solution to this in the short term.

[Sebaroni]

Hi, @Raja-Simha . Sorry it took me a while to reply: basically what @kago-dk and @gerhardvr-finclude said above: the development team generates OAS3 files as part of the API development process and these files are the source of truth, in a way, so I want to port these files to Postman to automatically generate the documentation for our public APIs. However, Postman does not automatically render body-parameter data types and descriptions in the documentation section, which is something Readme and Redoc already do. Instead, I would have to write the tables with request body parameter descriptions manually using markdown in the documentation section, which is not ideal, since it's a cumbersome process that could introduce errors and inaccuracies.

[kago-dk]

@Raja-Simha What is the latest status on this?

[tainmar]

@Raja-Simha Up on this one as it is really required. Our workflow is very similar to @Sebaroni 's one. Thank you for your update

[Raja-Simha]

Hey @Sebaroni @gerhardvr-finclude @kago-dk @tainmar Firstly, thanks again for the detailed description and reaching out to us.

Secondly, I am happy to let you guys know that you can now generate documentation from your OpenAPI 3.0 schema. You can try out the feature as explained here.

As we make further improvements, we'd love your feedback on API schema documentation. Do share your thoughts with us once you have tried it out. If you'd like to connect and discuss over a call, feel free to schedule one here.

[tainmar]

Thank you @Raja-Simha, Unfortunately, we are getting an error because the objects we manipulate are too deep (12 levels) and you are limiting to 8 levels. <Error: Too many levels of nesting to fake this schema>

[shashankawasthi88]

Hi,

I’m Shashank, a Product Manager at Postman. We’re exploring ideas for adding the ability to document request/response bodies, parameters, and more. This will allow you to provide additional details such as description, possible values, formats etc. for your JSON bodies and parameters as well.

This will also enhance the request sending experience, where you can select the possible value using a drop down. Also provide validation on the values the consumers are trying to send.

Here is a recording of what the feature might look like. You can read more about the feature here.

This is in its early stages, and we’re seeking early adopters to try it out and provide feedback. If you’re interested, please reach out to me at shashank.awasthi@postman.com or schedule a call using this link.

@tainmar @Sebaroni @kago-dk @gerhardvr-finclude