Open tomalrussell opened 5 years ago
@tomalrussell the libraries are https://www.npmjs.com/package/typescript-rest and https://www.npmjs.com/package/typescript-rest-swagger - they aren't hugely popular right now so might be something to consider. I have used them in a couple projects
Thanks @mz8i - looks like https://www.npmjs.com/package/tsoa is in the space and may be worth evaluating too.
Can you evaluate options and put together a proof of concept?
By default, I'd be cautious about adding dependencies and might prefer just using the swagger codegen to stub out methods and generate static HTML UI. I'm happy to look at what's available, though, and keen to see some running code that we can test out,
The key goals as far as I see it are:
tsoa
looks good too. I don't have experience with it but it seems to be slightly more popular.
So far the differences I can see are:
tsoa
contains swagger generation functionality, while typescript-rest
needs to be used together with typescript-rest-swagger
typescript-rest
sets up the routes at run-time whereas tsoa
requires running a code generation step for generating the route filestypescript-rest
is tied to Express whereas tsoa
, due to its code generation approach, can target different middlewares like Express, Koa etcIt is worth noting that using any of the above relies on colouring-cities/colouring-core#348 (switching to TypeScript) - so that needs discussing and potentially implementing first.
The alternatives would be:
I do like the sound of swagger-jsdoc: seems pretty pragmatic, relatively quick win option.
I think the API should never grow too big, so not too too worried about keeping it consistent - the main thing will be keeping on top of building attributes as we fill out the remaining sections.
So, suggest:
I started out with moving out the buildings API code into a routes file and a controller file to decrease the size of server.js
a bit: https://github.com/mz8i/colouring-london/commit/330642c89761e59f6d9d73d9d55d70655d8aac49
I also manually created an initial openapi.yml (Swagger is now called OpenAPI) file with the specification of some of the endpoints: https://github.com/mz8i/colouring-london/commit/bd1645c34c60da9fcaa7ea725434cdb2fd9c0ced
Some thoughts:
POST /building/:building_id.json
rely on user_id
in user session. Swagger has some options for describing authorization but I am not sure if this particular method will be possible to describe in the spec.Any comments welcome, otherwise I will continue describing the other endpoints and possibly refactoring.
@matkoniecz can you close?
Depends on whether we want to have documentation of API and plan to spend time on that.
Good documentation would be useful for more automated edits.
@matkoniecz shall I move to core then for discussion with international group?
yes
Initial setup and documentation for the core buildings API call:
GET /buildings/<building_id>
currently implemented in https://github.com/tomalrussell/colouring-london/blob/ad77e8345c4ae526a38592af8ea799f6d39c8b15/app/src/server.js#L194-L195GET /buildings
not currently implemented - will need pagination!Resources
@mz8i do you have a link for the typescript-swagger tool you mentioned earlier?