api

api copied to clipboard

Swagger 2.0 documentation for Pelias API.

Using swagger-jsdoc and express-swaggerize-ui, Swagger documentation is now generated and served upon npm start, compiling API information commented inline on routes/v1.js.

URLs:

• Viewing Swagger UI: <pelias-api>/api-docs
• Viewing Swagger JSON document: <pelias-api>/api-docs.json

wow looks cool, we will need a bit of time to test and review it!

@gibranparvez would it be possible to change the links from the venicegeo org to something within the pelias org, maybe https://github.com/pelias/documentation if the docs exists there?

Also, the markdown comment blocks are pretty verbose, is it possible to put them in another file? I'm not familiar with how swagger works.

@missinglink That sounds good. I've seen that traditionally the comment blocks are put inline, but in our case, it is indeed overly verbose and I can move larger model definitions and long parameter blocks to a separate json.

Any reference to VeniceGeo in this PR is something I've overlooked when I cherry-picked changes we've already merged into our fork and I will remove them shortly- my mistake.

@missinglink Would it instead be more appropriate to simply attach the separate json file? Currently it's being generated, but if this data is going to largely be static and not recorded inline, generating it from an external file (not v1.js) would pretty much be the same thing as simply having the static swagger.json file served. Thoughts? @orangejulius

please, this PR could it be merged?

I would also need the swagger file .. even if it is not complete with all the parameters of the endpoints, but I think it is very useful to everyone in many projects.

many thanks!