API doc generator

[dwilde1]

Hello, Delton Ding!

I'm very interested! I have worked with Sinatra for an API server for tablets, phones and HTML and I'm back again.

Several things I see that I'd like to mention. First, I see that you're already in WebSockets in a big way. Good work; I think that's one of the biggest development pushes out tehre now that it is finally stabilizing (!!!). Have you given thought to incorporating Swagger/OpenAPI and its editor, since they already do Sinatra?

Secondly, I haven't needed it before but see the need now more than ever, is authentication of APIs. I never got close enough to production before but now see a pressing need for OAUTH2 and API-Key authentication. I like what Timi Ajiboye's Client Manager does in terms of functionality but don't want the whole Rails framework chewing up CPU cycles. Maybe a simple CL DSL loop?

[dwilde1]

On Swagger, the OpenAPI-2.0 spec seems very clear. It should be elegant and not too involved to replace the Java bloatware of the first implementation. ;-) I just finished a Ruby implementation of a parser for the entire TR-181 data model for TR-069 device management and it took me less than 2 weeks to do it including the FOXtoolkit GUI I'm (still) refining.

Anyway, if you'll take a look at the authentication piece I'll look at Swagger and em-midori with an eye to streamlining their implementation with Ruby. I frankly admit that I'm not a security or web authentication expert, I only know what I need, so I'd appreciate if you'd add that to your to-do stack. I think the need is clear.

<bless> for the work you have already achieved! I have a real project I'm working on and a real day job, so I don't have 100% to spend on this but you've convinced me that a) you have talent and b) this is worth supporting.

[dsh0416]

Sorry for the late reply. As one of the principles I followed when defining the route APIs is that route definition could take the place of API docs. One of the example provided as following:

 get '/user/login' do
    define_error :forbidden_request, :unauthorized_error
    begin
      request = JSON.parse(@request.body)
      Midori::Response.new(200, UserController.login(request['username'], request['password']).to_json)
      # => {code: 0, token: String}
    rescue ForbiddenRequest => _e
      Midori::Response.new(403, {code: 403, message: 'Illegal request'}.to_json)
    rescue UnauthorizedError => _e
      Midori::Response.new(401, {code: 401, message: 'Incorrect username or password'}.to_json)
    rescue => _e
      Midori::Response.new(400, {code: 400, message: 'Bad Request'}.to_json)
    end
  end

The route definition not only shows which Controller to use, but also how request and response are, all possible errors and how to handle them. With the help of middlewares, this definition could be further simplified.
But still, providing a testable API docs like Swagger could be better. But the priority for the now time is not very high, cause the API is still not stabilized. What's more, @jasl is now working on changing the route matching to a better engine and provides more flexibility. I believe that we should make this a bit later.

[pchaganti]

👍