Swagger API Documentation #1474
Conversation
| @@ -1,87 +0,0 @@ | |||
| import { api, Action } from "./../index"; | |||
There was a problem hiding this comment.
Any reason to leave this action around for backwards compatibility?
| summary: action.description, | ||
| // description: action.description, // this is redundant | ||
| consumes: ["application/json"], | ||
| produces: ["application/json"], |
There was a problem hiding this comment.
Do our actions always consume and produce application/json?
| default: | ||
| action.inputs[inputName].default !== null && | ||
| action.inputs[inputName].default !== undefined | ||
| ? typeof action.inputs[inputName].default === "object" |
There was a problem hiding this comment.
Typescript doesn't give us something better than typeof of === "object"?
There was a problem hiding this comment.
not that I've found yet :(
|
Great questions @gcoonrod, and thanks for the review! I think that this action is a lot like As far as backwards-compatibility goes, I got the sense that no one was really using the |
| securityDefinitions: { | ||
| // TODO (custom)? | ||
| }, |
There was a problem hiding this comment.
Here's an example of a securityDefinitions https://github.com/grouparoo/grouparoo/blob/master/core/api/src/actions/swagger.ts#L134-L145
For years, Actionhero has shipped with a
showDocumentationaction that provided a way to describe the actions running on your server. The action was used to self-document the abilities of your server. However, the format of that action is arbitrary... and not helpful in a larger ecosystem.Switching the format of this action to swagger/OpenAPI will make the Action much more useful.
showDocumentationaction withswaggeraction. Remove all old references toshowDocumentationswagger.htmlandswaggeraction in generated projects which can consume and demo the APIinitializer/documentation, as we don't need this documentation internally without the old showDocumentation action.The breaking change is only around the
showDocumentationanddocumentationinitializer, which appears to not be used very much.Closes #1470