What is the best way to document POST-body parameters?

johannes
Participant I

Hi!

We're using swagger to populate the documentation of our endpoints in the Developer Portal. Recently we've added POST-endpoints and we're wondering about the best way to document the parameters in the POST-body. I'd be curious how you document POST endpoints. Screenshots would be a great help.

Thanks!

Solved Solved
0 11 1,875
1 ACCEPTED SOLUTION

kengilbert-1
Participant II

If you're already using SmartDocs in the developer portal to document your APIs via a swagger spec. then documenting POST body parameters should be fairly easy and straight-forward.

You should simply need document your body parameters using the markdown supported by the Swagger spec. indicated here. After importing your spec., SmartDocs will create a "Request Body" section that users can use to send live requests against the API.

5779-screen-shot-2017-10-16-at-120153-pm.png

View solution in original post

11 REPLIES 11

kengilbert-1
Participant II

If you're already using SmartDocs in the developer portal to document your APIs via a swagger spec. then documenting POST body parameters should be fairly easy and straight-forward.

You should simply need document your body parameters using the markdown supported by the Swagger spec. indicated here. After importing your spec., SmartDocs will create a "Request Body" section that users can use to send live requests against the API.

5779-screen-shot-2017-10-16-at-120153-pm.png

Thanks!

That sounds good. How would I add a description to the parameters though? Or indicate that some are optional/mandatory?

Thanks!

You'd specify additional attributes in the schema of the Swagger spec. There's a "required" attribute you can use to indicate a required body param. For description, you should be able to simply add a "description" attribute underneath the "type" attribute seen here describing the type of the parameter.

I see what you're saying. But that wouldn't 'describe' each parameter. I would describe the endpoint as a whole. The Dev Portal does a great job for GETs: listing each parameter + description. I was kinda wondering if there's a way to get that behavior for POSTs as well.

@johannes1 Smartdocs does have a way to add a description of the body params. See the doc here:

https://docs.apigee.com/developer-services/content/using-smartdocs-document-apis#addingapistoamodel-...

You can see an example in the Edge API for this POST:

https://docs.apigee.com/management/apis/post/organizations/%7Borg_name%7D/apiproducts

Stephen

Thanks @sgilson that was exactly what I was searching. Now I have to figure out how I get the post body parameters in the tabular format.


You can use HTML table tags.

@johannes1 ,

You need to edit the template to make it happen. It's actually asked by many people. I am working on same. I will keep you posted.

@Chris Novak , @marshg@google.com FYI..

@sgilson , I am sure above html table is hardcoded into description. I have seen multiple instances where our customers asked for this capability out of the box - auto generated from OpenAPI spec.

@johannes1 ,

Please find the article that describes the solution you are looking for. Hope it helps.

Keep us posted if any using comments in above article page.