There are various APIs, being used in the Release engineering of mozilla, and there is no standard way to actually document them,publishing them and generating client libraries for them. So as suggested by Pete Moore in
https://wiki.mozilla.org/Community:SummerOfCode15#Release_Engineering.I have been looking for various ways of doing this using JSON schema and Hyperschema.
This seems to be a very simple way of documenting the API, and swagger makes it simpler for us. And also it will make very easy for the new developers and contributors to actually understand the API, by just seeing the JSON schema.
There are 5 APIs which are planned to be covered under this project.
1.Build-API: https://wiki.mozilla.org/ReleaseEngineering/Applications/BuildAPI
2.Clobberer: https://api.pub.build.mozilla.org/docs/usage/clobberer/#endpoints
3.Mapper: https://wiki.mozilla.org/ReleaseEngineering/Applications/Mapper
4.Mozpool: http://hg.mozilla.org/build/mozpool/file/tip/API.txt
5.Slave API: http://mozilla-slaveapi.readthedocs.org/en/latest/api/#slaves-slave-actions-disable
What is Swagger?
Swagger basically allows us to document our API using JSON schema, giving us various plugins so that this JSON schema can be used to do various things regarding the documentation for easy understanding of the API.
https://github.com/swagger-api/swagger-core
How to use Swagger?
The step one is to write a swagger specification. Swagger specification is a format of writing the JSON schema , so that various plugins can use that schema for further use. This can be done using the swagger editor (a plugin which facilitates us to write swagger specification). So here we go , this was all the manual part.
https://github.com/swagger-api/swagger-editor
The second step will be to have a GUI for this specification. For this we will be using swagger UI plugin , which basically takes in the swagger specification and gives a nice interactive user interface which can be used to learn the functionality of these APIs. This will be a really unconventional way for documenting an API and it would really facilitate our new contributors to know about the APIs very quickly.
https://github.com/swagger-api/swagger-ui
The third part will be auto-generating the client libraries for these APIs. Again swagger comes to rescue. We will use the swagger codogen plugin for this purpose. Again we simply have to give the swagger specification as the input and we get client libraries as the output.
The last part will be to write scripts that publish the documentation to a central
location.
https://github.com/swagger-api/swagger-codegen
The main strength of using swagger is the swagger UI , which will allow developers to understand the functionality and the potential of the API without actually looking at the code.
