How do you document HTTP requests on a REST endpoint
-
On a NodeJS/Express app we're documenting our endpoints like:
/** * A GET request like /api/foo?key=1234 * @param {Integer} foo - foo */
How would I document that this endpoints requires an specific HTTP header like "Accept" and the options required: "application/json"?
-
@Eldelshell You're probably overthinking this
/** * A GET request like /api/foo?key=1234 * Requires 'Accept: application/json' for json return * @param {Integer} foo - foo */
-
@Eldelshell Are you using some API documentation generator? If you are, then see what format they expect. If not, just do what @Yamikuronue said.
-
@Eldelshell
For javadoc @Yamikuronue's suggestion should be sufficient, for external documentation you might want to take a look at http://swagger.io.
-
Sorry, I should have mentioned we're using JSDoc although we could change to something else.
-
@Eldelshell said in How do you document HTTP requests on a REST endpoint:
JSDoc
in theat case i'll second @Yamikuronue's sugestion.
-
@Eldelshell I'm curious: are you going to put the Accept header thing on every endpoint? Because that's the sort of thing that's better documented on a summary page or something, rather than each endpoint.
-
@Eldelshell said in How do you document HTTP requests on a REST endpoint:
How would I document that this endpoints requires an specific HTTP header like "Accept" and the options required: "application/json"?
... read the documentation of whatever documentation-generator library you're using? Why would you ask here?
-
@Yamikuronue Nicely done dear.
-
@RaceProUK only on some endpoints certain headers are required and I want this to be documented. Also, some endpoints return xml or json based on the accept header but anything else will return a 400.
-
@Yamikuronue said in How do you document HTTP requests on a REST endpoint:
@Eldelshell You're probably overthinking this
I agree.