search

jedireza / frame

:bulb: A user system API starter
https://jedireza.github.io/frame/
MIT License
740 stars 157 forks source link

Add swagger docs metadata #218

Closed fishmongr closed 6 years ago

fishmongr commented 6 years ago

Per our discussion I added real and very helpful Swagger doc metadata updates. I didn't add any endpoint Joi schema updates only helpful description fields at the document level, tag level, and endpoint level including helpful scope information. This is what it looks like in the live Swagger UI available at /documentation when deployed: https://www.dropbox.com/s/33wabeyxu446rhf/Screenshot%202018-05-30%2011.55.16.png?dl=0

fishmongr commented 6 years ago

Thanks for the quick feedback Jedireza. Whoops, corrected the mixed spaces and tabs issue.

Re: Displaying the permission scope up-front in docs I think it's pretty important that API users, especially front-end devs who are hooking up endpoints to FE code be able to get all the information they need around the endpoints from the swagger docs alone. The docs are a black box contract, like an interface, they shouldn't be expected to have to dig into the Node route code and models to figure out why a call isn't returning as expected due to a scope issue.

I don't think there is an easy way to make it dynamic without a lot of extra code since 'root' scope is buried in pre:, etc. In my opinion it's important enough to keep but your call, I can remove it.

fishmongr commented 6 years ago

BTW Aqua is amazing as a user/dev portal boilerplate built on top of Frame. It appears to have significantly more adoption and interest based on stars/forks then Frame as folks want an all-in-one boilerplate solution for both back-end and front-end. I am in that boat and am using it for a major project but it sucks to see it archived.

I've been working with the hapi-17-async-await branch, added the same Swagger docs updates, several bug fixes, I'd like to push some updates to it and keep that project alive. Think it's worthwhile?

jedireza commented 6 years ago

I don't think there is an easy way to make it dynamic without a lot of extra code since 'root' scope is buried in pre:, etc. In my opinion it's important enough to keep but your call, I can remove it.

Ok, let's leave it. I wonder if lout would be better and more hapi friendly in this (scope) regard.

Aqua is amazing ... it sucks to see it archived

Thanks, I'm glad you found it useful. It was a hard decision to archive it, but it's a pretty significant time sink and while I got a PR every now and then, I was the sole maintainer.

I've been working with the hapi-17-async-await branch, added the same Swagger docs updates, several bug fixes, I'd like to push some updates to it and keep that project alive. Think it's worthwhile?

That's rad! I wish I had time to focus on incorporating your changes there.

fishmongr commented 6 years ago

Awesome thanks!

I checked out lout but it looked pretty basic compared to what Swagger offers out of the box. With Swagger's interactive docs you don't have to fiddle with Postman and it's got enough polish in boilerplate docs UI that it can be easily integrated in client facing projects. The V3 version of Swagger UI was a complete re-write from Backbone to React as well and looks and performs a lot better then the current v2 in Hapi-Swagger.

Swagger was actually donated to Apache and renamed to "OpenAPI Specification" for v3 not too long ago so I think will only get more popular. There is also a lot of nice open source tooling around the swagger.json file not just documentation generation, like using it to automatically stub out SDKs in multiple languages against your API. I like that Swagger's ecosystem is language agnostic so can be used easily across projects that way.

Re: Aqua, why not leave it open and allow the pull requests to pile up, that's what everyone else does ;)

Anyways, thanks for the efforts, i'll continue to support how I can!