Feathers: A swagger plugin for automatic API docs

[norman784]

Also a must have feature, if you want to share your api to other developers

var todos = {
  version: 1,
  find: {
    doc : {
        description: 'Return a todo list',
        // The params that the method receive
        params: [ { 
          name: 'limit', 
          description: 'determine the number of items to return',
          type: 'numeric',
          required: false
        } ],
        // An output example
        output: [{
           name: 'Todo name',
           status: 'finished'
        }]
    }
    method: function(params...){...}
  }
}

feathers().configure('documentation', true)....

Then you can call it just like GET /v1/docs/todos if documentation is set to false it the docs path will not be initialised

It was inspired on Action Hero api documentation method

[daffl]

What would be really cool is if we could parse that out of the services inline documentation to generate a documentation page.

var todoService = {
    /**
     * Returns a single Todo
     * 
     * @param {string} id The Todos name
     * @param {Object} params Service parameters 
     * @param {Function} callback Success callback
     */
    get: function(id, params, callback) {

    }
  }

[norman784]

Seems much better solution, YUI doc will parse this kind of documentation, only need to see witch option is better and see how integrate it. I like the automation, some don't

[pspeter3]

I think automatic RAML documentation would be the way to go

[gr0uch]

Why not implement standards like JSON Schema and JSON API?

[pspeter3]

RAML is an upcoming API standard for REST APIs that uses JSON Schema

[daffl]

I quickly read through the docs and I still can't see what benefit I would get from generating RAML? The reason I'm asking is because I have yet to see a standard, that describes semantics, succeed (RDF anyone?). What are the advantages vs. just generating an HTML page from the documentation?

[gr0uch]

I think the idea is that this sort of documentation can be serialized by machines, and theoretically a client can consume an APi using this serialization format. Still, it is out-of-band information and prone to falling behind what the API might actually emit.

[pspeter3]

Well there is already a RAML documentation generator and I'm sure more will come but the bigger win is that they're working on client generation.

[daffl]

To me Feathers service concept seems like a more pragmatic approach to what RAML is supposed to describe. i totally agree with their statement saying

We say "practically RESTful" because, today in the real world, very few APIs today actually obey all constraints of REST.

This is actually one of the reasons why Feathers came to exist. Making the REST-provider more compliant to those constraints is definitely one of the things I'd love to see in the future.

I thought however that the whole point of an ideal REST service is discoverability, linking between resources and a unified interface so that it doesn't need a description format in the first place?

[pspeter3]

That's true but that still doesn't help with automatic client generation

[Glavin001]

I actually liked the structure that @norman784 was suggesting initially. Essentially merging the structures of Feathers Services with something like Swagger's.

Could Feathers documentation generator export to the Swagger documentation JSON? See https://github.com/wordnik/swagger-core/wiki/API-Declaration

I really like how Swagger displays the API docs: http://petstore.swagger.wordnik.com/#!/user
Example service documentation JSON: http://petstore.swagger.wordnik.com/api/api-docs/user

[norman784]

My idea isn't for automatic client generation, but it's to create a documentation for other developers, so you will be document your api as you develop it, thats all.

Swagger seems interesting too.

[Glavin001]

Yeah, that's what I had thought you meant, too. Documentation for other developers on the REST / Socket.io service provided by Feathers.

I like what @daffl said (except we extract the services documentation from the JSON structure):

What would be really cool is if we could parse that out of the services inline documentation to generate a documentation page.

I suppose the confusion is when I said _documentation generator_. I mean in that sense that we may have one JSON structure for describing documentation in Feathers' services, and that may not directly match Swagger's, so therefore some conversion from Feathers format to Swaggers would have to be made.

This could potentially be a plugin. That would likely be preferable: have Feathers allow a doc field and various attributes such as description, and then plugins that handle creating the services for presenting documentation.

var feathersSwagger = require("feathers-swagger");
feathers().configure(feathersSwagger).configure('documentation', true)....

In this fashion, we again only have to change the Services in JavaScript and then both the API and the documentation will both come out of that, however we choose to render that, potentially with a plugin.

[Glavin001]

For those following this issue, I am starting a plugin: feathers-swagger.

[daffl]

I'm closing this issue here. I think feathers-swagger solves this issue pretty nicely and we can follow up on it there, plugins for other formats are more than welcome, too.

@Glavin001 Any plans on moving it into the organization?

[Glavin001]

I think feathers-swagger solves this issue pretty nicely

Thanks, @daffl!

Any plans on moving it into the organization?

Sure, I'll take care of that later tonight :+1:.

[bkniffler]

Hey, any news on moving this to feathersjs org? Having something like swagger would be a great addition for feathers.

[ekryski]

@bkniffler I actually forgot about this! If @Glavin001 is willing to transfer it then yes we'll take it. It was written against 1.0 so might need some work in order to be compatible for 2.0 but probably not much.

I guess the only downer is this only accounts for HTTP(s) documentation and not Websockets but it would be a great addition.

[ekryski]

Re-opening for visiblity.

[Glavin001]

I also forgot about this! I have transferred feathers-swagger into the feathersjs organization.

[kulakowka]

I like the way it is implemented in GraphQL and debugging GraphiQL. The documentation is built into the application itself.

[bkniffler]

GraphQL is build on strong schema definitions that are part of the API endpoint, which makes it much easier to write something like GraphiQL. Feathers doesn't have a clue about the data it serves. So you could either use comments and generate documentation out of them like @daffl pointed out or you let feathers understand its ORMs data schemas (https://github.com/feathersjs/feathers/issues/271) so it can create documentations automatically.

[ekryski]

Thanks @Glavin001! We'll probably need to you to add one of us as owners to the npm repo as well. :smile:

[Glavin001]

Looks like you and @daffl are owners now :smile: : https://www.npmjs.com/package/feathers-swagger
Let me know if there is anything else I can do!

[ekryski]

@Glavin001 Wicked! Thanks mate!

[daffl]

An updated version of https://github.com/feathersjs/feathers-swagger has been released and is ready to use (see the example).

[lock[bot]]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue with a link to this issue for related bugs.