Add swagger API docs #62
Conversation
Pull Request Test Coverage Report for Build 55
💛 - Coveralls |
Pull Request Test Coverage Report for Build 83
💛 - Coveralls |
docs/swagger.yml
Outdated
| in: query | ||
| name: $skip | ||
| type: integer | ||
| - description: Property to sort results |
There was a problem hiding this comment.
Maybe change this to "Property to sort results by"?
There was a problem hiding this comment.
Should we also name what properties are accepted? ASC/DESC or the whole word?
docs/swagger.yml
Outdated
| - name: events | ||
| description: Endpoint handling incoming events. You usually should not use this endpoint directly and instead rely on the RabbitMQ integration to deliver events. The RabbitMQ integration will call this endpoint internally. | ||
| - name: achievements | ||
| description: Endpoint returning a list of all granted achievements. You usually should not use this endpoint directly and instead rely on the /user endpoint for retrieving granted achievements by user. |
There was a problem hiding this comment.
I'd say "granted to a user" is more accurate than "by user".
docs/swagger.yml
Outdated
| - name: user | ||
| description: Retrieve gamification data for a user. | ||
| - name: events | ||
| description: Endpoint handling incoming events. You usually should not use this endpoint directly and instead rely on the RabbitMQ integration to deliver events. The RabbitMQ integration will call this endpoint internally. |
There was a problem hiding this comment.
"In general, you should ..." instead of "You usually should". I think it sounds nicer that way.
src/app.js
Outdated
| @@ -48,6 +55,6 @@ app.use(express.errorHandler({ logger })); | |||
|
|
|||
| app.hooks(appHooks); | |||
|
|
|||
| app.set('rules', require('./rule-parser')(__dirname + '/../config/gamification.yml')); | |||
| app.set('rules', require('./rule-parser')(path.join(__dirname, '..', 'config', 'gamification.yml'))); | |||
There was a problem hiding this comment.
Good catch! We should probably do that in the tests as well.
docs/swagger.yml
Outdated
| in: query | ||
| name: $skip | ||
| type: integer | ||
| - description: Property to sort results |
There was a problem hiding this comment.
Should we also name what properties are accepted? ASC/DESC or the whole word?
docs/swagger.yml
Outdated
| description: not authenticated | ||
| '500': | ||
| description: general error | ||
| description: Retrieves a list of all resources from the service. |
There was a problem hiding this comment.
Resources? What resources? This seems like a general description for get and not specific to each request?
|
Both of you are right, I was a bit lazy initially and auto-generated the definitions. Then I ditched the auto-generation and manually adjusted the output, however, without paying too much attention, as it seems. I think I now improved the config quite a bit and would welcome another review @corinnaj @frederike-ramin. |
Part of #25. The docs are available at
localhost:3030/docs.