Is there an automated way to document Nancy services?

Question

Is there any way to auto-generate Swagger documentation (or similar) for a Nancy service?

I found Nancy.Swagger, but there's no information on how to use it and the demo application doesn't seem to demonstrate generating documentation (if it does, it's not obvious).

Any help would be appreciated. Thanks!

Answer 1

No. Not in an automated. https://github.com/yahehe/Nancy.Swagger needs lots of manually created metadata.

Answer 2

In my current project I've been looking a lot into this problem. I used both nancy.swagger and nancy.swagger.attributes.

I quickly discarded Nancy.swagger, because for me personally it doesn't sound right that you have to create a pure documentation class for each nancy module. The attributes solution was a bit "cleaner" - at least codebase and documentation were in one place. But very fast this became unmaintainable. Module code is unreadable because of many attributes. Nothing is generated automatically: you have to put path, all parameters, even http method as an attribute. This is a huge effort duplication. Problems came very fast, a few examples:

• I changed POST to PUT in Nancy and forgot to update [Method] attribute.
• I added a parameter but not the attribute for it.
• I changed parameter from path to query and didn't update the attribute.

It's too easy to forget to update the attributes (let alone documentation module solution), which leads to discrepancies between your documentation and actual code base. Our UI team is in another country and they had some trouble using the APIs because docu just wasn't up-to-date.

My solution? Don't mix code and documentation. Generating docu from code (like Swashbuckle does) IS ok, but actually writing docu in code and try to dublicate the code in docu is NOT. It's not better than writing it in a Word document for your clients.

If you want Swagger docu, just do it the Swagger way. - Spend some time with Swagger.Editor and really author your API in YAML. It looks all-text and hard, but once you get used to it, it's not. - Spend some time with Swagger.Codegen and adapt it (it already does a fair job for generating Nancy server code and with a few adjustments to moustache templates it was just what I needed). - Automate your process: write a couple of batches to generate your modules and models from yaml and copy them to your repository.

Benefits? Quite a few: -

• Your YAML definition is now the single truth of your REST contract. If somewhere something is defferent, it's wrong.
• Nancy server code is auto-generated
• Client code-bases are auto-generated (in our case it's android, ios and angular)

So whenever I change something in REST contract, all codebases are regenerated and added to projects in one batch. I just have to tell the teams something was updated. They don't have to look through some documents and search for it. They just have their code regenerated and probably see some compile errors, in case of breaking changes.

Do I still use nancy.swagger(.annotations)? Yes, I do use it in another project, which has just one endpoint with a couple of methods. They don't change often. It's not worth the effort to set up everything, I have my swagger docu fast up and running. But if your project is big, API is changing, and you have multiple code-bases depending on your API, my advice is to invest some time into a real swagger setup.

Answer 3

I am quoting the author answer here from https://github.com/khellang/Nancy.Swagger/issues/59

The installation should be really simple, just pull down the NuGet package, add metadata modules to describe your routes, and hit /api-docs. That should get you the JSON. If you want to add swagger-ui as well, you have to add that manually right now.