In openmrs Swagger documentation , we use POST as a request method that creates a new resource and also as a request method that updates an existing resource.
for better and easy understanding, i think it would be called PUT as thats the general used name for an updating-request method .
Could there be a reason why we still had to call the updating -request method POST ??
To be truly RESTful, we would use the HTTP verbs:
However, this is an issue of implementation and not documentation, meaning we should document what is implemented in the REST API. It actually makes things worse if we document PUT in Swagger when the API requires a POST method.
Unfortunately, I think most cases where PUT or PATCH should be used, we use POST. I think it’s because (at least around 2012, when the REST API was being created) it was easier for clients to use POST compared to PUT or PATCH methods. I would prefer if we supported conventional verbs. Maybe we could have a hackathon to implement them (keeping POST support for backwards compatibility). In any case, our documentation needs to reflect what the API actually uses, whether we like it or not. 
oh ya thats true
that would be better , other wise at quick glance at our document, its hard to differentiate between what creates and what updates, unless you take a more deeper look .
