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!
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.
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:
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.
Check this out https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-1-introduction/
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.
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.
