title: Is it a good practice to publicly document an open API?
body: <p>Everybody can be sure of the benefits and the drawbacks of an open API. </p>
  
  <p>But is it a good or a bad practice to publicly document the open API (which requires authentication for its requests)?</p>
  
  <p>By publicly document I mean creating a documentation showing the structure of the body of the request that the API can receive and by giving descriptions for all these fields.</p>
  
  <p>Eg, given an endpoint <code>my-public.url/myendpoint/myresource</code>, with available <code>PUT</code>, <code>POST</code>, <code>DELETE</code> and <code>GET</code> http requests there's a static page <code>my-public.url/document/myendpoint</code>which shows all the acceptable http requests along with description for the headers and the body of the request that are needed in order to perform it. </p>
  
  <p>On the one side, this will help external developers to use the API easily, but on the other hand, if somebody gains access somehow, it would be easy for them to make requests and corrupt the system, since the whole structure of the API is given. </p>