2

I am currently working on a project where we will integrate salesforce with a couple of other tools in the company's processes. For doing so, I will develop a lot of endpoints (20-30 ressources, I guess).

Now I was wondering: How to best document all my API endpoints? I do a lot of my technical documentation in Confluence+JIRA and have not that much routine in working with APIs (I know about tools like Swagger or Apiary, though). Is there a better approach to do that for salesforce APIs?

1

This is unrelated to Salesforce but salesforce does not provide any native tooling to document your Custom REST API .Instead I would explore Swagger to assist me with the tooling .

Swagger Editor is commonly used by most of the open source projects to document the API with sample request and response structures .

  • 1
    Swagger IS awesome! – John Thompson Jan 26 '18 at 15:01
  • Thank you very much. This will be especially usefull, when we want to document our enterprise API in general and not only my very personal salesforce APIs. – J. Lietzau Jan 29 '18 at 13:58
  • I decided to use a combination of 10% confluence and 90% swagger. I do the complete technical documentation in swagger and confluence holds the road map, my general concepts and requirements. I am very happy with this solution. – J. Lietzau Apr 19 '18 at 7:16
1

I've had to document APIs (mostly REST for me...), and I do it in Confluence. It's typically based on a table with headers like:

  • resource
  • version
  • URI
  • HTTP method
  • description
  • example

You might want others...

The win for the API consumers (the thing they like the BEST), is that the example column has a link to another page. On those example pages there are Code block macros with additional details of what needs to be in the request body, and the JSON returned. I get the return JSON by using the REST explorer in Workbench... copy/paste the raw response.

Anyway that's what I do....

Bonus points: The REST explorer is also a GREAT way to perform a functional test of your new custom Apex REST resource!

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.