Kuzzle becomes swagger everyday

Today, Kuzzle has gained Swagger support. Swagger is a powerful way to describe an API. It allows to take advantage of many tools. It also pushes Kuzzle’s API to the next level. In this article, you’ll get an overview of what is cool in Swagger and why we decided to implement it into Kuzzle.

Today, Kuzzle becomes swagger.

No. Not that kind of swag, this kind:

WHAT IS SWAGGER?

Swagger is a formal representation of a RESTful API. It describes URLs, parameters, outputs, types and formats. With Swagger, you can generate powerful interactive documentation, client SDK generation and discoverability.

Why is it cool?

INTERACTIVE DOCUMENTATION

By using the documentation generator aka swagger-ui, which is open-source, you can create a documentation for your API within minutes. The only prerequisites are to… have nodeJs properly installed (see the Swagger-ui documentation to get more information).

Here is how to generate your very own interactive documentation in less than 3 minutes:

Simply git clone the project:

git clone https://github.com/swagger-api/swagger-ui.git && cd swagger-ui

Edit the template file to replace the default swagger.json URL by yours. If you have Kuzzle installed in localhost, just use http://localhost:7511/api/swagger.json. In one line of code:
```
sed -i 's/http:\/\/petstore.swagger.io\/v2\/swagger.json/http:\/\/localhost:7511\/api\/swagger.json/g' ./src/main/html/index.html
```
Install dependencies:
```
npm install
```
Build the documentation:
```
npm run build
```
Open the dist/index.html file into your favourite browser
Enjoy.

See it live:

CLIENT & SERVER GENERATION

One of the swag thing is that you can generate within seconds a server or a client for your API in many languages.

Clients and servers come with tests, readme, etc. Keep in mind that if you don’t describe all the routes, parameters and responses properly, along with authentication mechanisms, the generated code will be quite buggy and not fully usable.

MANY TOOLS

Swagger is not a lonesome project. It comes with many tools. One of the main and useful tool is the editor.

Thanks to it, you can validate your Swagger files and see instantly how the auto generated documentation will look like.

You can also import & export in several formats and generate servers or clients.

The editor comes along with real-life examples and helps you to create great Swagger files.

WHAT ABOUT KUZZLE?

In Kuzzle, two routes are now available to retrieve a swagger file in both JSON and YAML formats. A CLI command allows you to generate those files if you need them directly from your server.

Given a Kuzzle server running on localhost, simply use http://localhost:7511/api/swagger.json or http://localhost:7511/api/swagger.yml to retrieve the Swagger representation of Kuzzle’s API.

As of today, most of the routes are not fully described: a script generates a minimal description for each route and parameters information are deducted from the URL route. The PUT and POST request bodies specs are missing. Considering that Kuzzle has more than 200 routes, it will be a hard time for us to fully document all of them (you are welcome to contribute ;))

WHY JUST NOW?

We probably should have done this in the early days of Kuzzle. We planned it a long time ago, but it was not an emergency. We preferred to make Kuzzle rock solid and blazing fast rather than swag. Doing it in the early stages of the Kuzzle design would have prevented us from having all the routes to be fully described in one time. So which one is better, doing it lately or never do it?

In the next days, we will describe all the routes properly, making Kuzzle swagger everyday.