Add a swagger.yaml file

[hansmbakker]

Description:
I created a swagger configuration file that will help people create clients (apps / frontends) for Home Assistant more easily. Based upon this code it is even possible to generate client code for several programming languages.

I created it by hand now, so when the API changes it will need to be updated. That's why it would be better to generate this specification automatically. This is possible for API frameworks but I don't know whether it is possible for the handwritten endpoints in Home Assistant. @balloob Maybe you could assist here?

This documentation could be used to replace a part of https://home-assistant.io/developers/rest_api/.

[hansmbakker]

I could not find any automated swagger generators for werkzeug, but I found that there are generators for e.g. flask and django.

Flask is a framework on top of werkzeug - @JshWright / @balloob did you consider using this framework when implementing werkzeug?

[JshWright]

We did. It was an added layer of abstraction we didn't really need. Because of Home Assistant's reasonably complicated architecture (the event bus, state machine, etc), it made sense to use a slightly lower level library for more fine-grained control.

Supporting 'swagger' obviously wasn't a design requirement.

[hansmbakker]

Ok, that's a clear answer. I can understand that you'd rather not introduce unneccessary dependencies.

However, I think being able to generate interactive API documentation is a really useful feature - for debugging & testing purposes and for easily generating client code and keeping client code up to date.

It would also result in less effort needed to keep the documentation pages about the REST api up to date.

Am I right that swagger (not the street word, but the API documentation standard) is something new to you, since you put it between accents? If so, then I'm wondering whether you, @balloob and others would be interested in it now.

For a quick demonstration I can recommend to read this article, or simply copy/paste the swagger.yaml file I committed in http://editor.swagger.io/ and see the interactive documentation it generates.

I for sure would like to have it, but I don't have the needed experience to implement a different http framework into Home Assistant. Also, I'd rather have your support since you just implemented another framework and it would be better to bundle efforts.

[JshWright]

I used quotes because it was standing in for any sort of API documentation standard (Swagger is the new kid on the block, in that regard).

If autogenerating docs is something we want to have right now (it may or may not be, I'd leave that up to @balloob), there are plenty of solutions that will work with the current implementation (Sphinx is pretty standard in the Python world).

[hansmbakker]

Ok. To clear things up - when I talked about "API" and "the API" I meant "Home Assistant's REST API".

I'm from the .Net world and have not much experience with Python. I don't know Sphinx yet, but it seems that it is meant to create generic documentation.

I see that Sphinx has an extension for REST API documentation and that it is possible to use reflection with e.g. flask but that the generated documentation is something plain - not interactive and not possible to generate client or mock server code with.

On the other hand Swagger is targeted specifically at REST API's and with Swagger it is possible to do these things. That's why I mentioned this tool; if there are any tools that can do that which people here prefer then I'd also like to hear about that.

[fabaff]

As far as I remember was @balloob playing around with a different tool in the past for the API documentation. Sorry, can't remember the name.

Having an interactive way to work with the HA API would be nice for people who don't want to use the present samples with curl or other command-line tools. I doubt that the Swagger Codegen is a killer feature which will attract a lot of people.

We should keep in mind that the API is not changing a lot and is a simple markdown file at the moment. So everybody with a basic knowledge about markdown is able to update it.

[hansmbakker]

As for "not changing much" probably you're right, but it can also lead to small mistakes. For example - in the rest API documentation page, a non-standard date time format is shown while actually the official date time format is used now.

Probably that was fixed but the documentation was not updated to reflect that fix.

That's where documentation generation is useful.

Also I read that somebody is writing an iOS client app at the moment - for such people interactive documentation and code generation would be certainly useful.

Until automated generation is there, my contributed swagger definition can be used.

[fabaff]

As for "not changing much" probably you're right, but it can also lead to small mistakes. For example - in the rest API documentation page, a non-standard date time format is shown while actually the official date time format is used now.

Our documentation is not different than for other fast moving projects...all the time three steps behind the actual code and partially obsolete, incomplete, and not up-to-date.

Probably that was fixed but the documentation was not updated to reflect that fix.

No, it was not fixed. Just did it now.

That's where documentation generation is useful.

HA.io is completely auto-generated and deployed. I think that we should check if a quick and easy integration is possible. Documentation generation doesn't help us to solve the issue of wrong or out-dated input but for the reduction of the amount of repetitive work. I'm all for automation if there is balance between invested and saved time for a task.

[balloob]

I like it. I think it is a great addition that will actually give us some usable docs. The current ones are in markdown and it just doesn't work well.

Could you move the file to the docs folder ? After that I'm down to merge this.

[hansmbakker]

@balloob I moved the file to the docs folder, thanks for the suggestion and feedback!

Do you have any thoughts on auto-generation of the yaml file?

[balloob]

Looks good! 🐬