Project goal: Find and implement the extraction of the REST APIs from the sources and generate and publish the REST APIs respective documentation
Skills to study/improve: Java, REST API, OpenAPI / Swagger
Developers need to know what to expect in terms of responses for each REST API endpoint, so external tools like jenkins-rest can be developed with confidence, and possibly with the help of some REST specification automation. For example, this could be done using the OpenAPI Specification (formerly known as Swagger Specification). Users of the REST API most often want:
HTTP responses and codes
Body of message and its format (e.g. JSON, html, etc.)
Jenkins does not have automated REST API documentation at all at this time. A lot of APIs are contributed from extensions, so there are multiple REST APIs (core and plugins) of varying versions. The goal of this project is to find and implement the extraction of the REST APIs from the sources and generate and publish the REST APIs respective documentation.
Generating the expected HTTP responses is a difficult task. The student is expected to study Jenkins core to identify ways to extract them. For example, they could be extracted from Javadocs and annotations.
As part of the community bonding and student project proposal phase, the student is expected to make a few proposals on how to specify and generate the REST API for the Jenkins core and for the plugins. In the case the student finds that it is not possible to generate the REST API from a specification, the student should identify why this is not possible. We also ask the student to explore and propose a way to have REST API of plugins be generated from a REST API specification. For example, some auto-code could populate what the javadoc would look like in an empty-plugin used by the maven plugin generator.
The student is also expected to study and propose how the REST API documentation generation could be part of the REST API generator.
It might be helpful to automatically generate some code for the REST API when the plugin developer creates a plugin for the first time using the plugin skeleton generator. Any methodology created to handle the REST API should be built into the skeleton generator.
The jenkins core REST API and the plugins own REST API need to be versioned separately. It is suggested to first focus first on generating the specification, then later look at the versioning of the REST API. Nested objects make versioning challenging.
Jenkins users should be easily able to see the REST APIs available for their installed Jenkins.
For Jenkins core, this could be done with a URL like:
The plugins would have their own REST API path with a version number like:
Plugins and the core would thus have their own version number, and an additional REST API version number. Automated API documentation using the OpenAPI 3.0 specification is part of identifying the API specs.
There are many examples of such documentation on the web:
Bitbucket REST API (link to Bitbucket documentation)
Artifactory REST API (link to Artifactory documentation)
OpenAPI3 description of the Jenkins REST API: swaggy jenkins (note: the swaggy-jenkins author now recommends OpenAPI (explanation).
This stackoverflow question talks briefly about generating a REST API spec in WADL format
A blog post that talks about swagger and WADL
Making Stapler more declarative discussion leading to a comment on swagger.
A google group discussion on seeking help on clarifying this proposal
Jira ticket JENKINS-35808 on generating spec for Jenkins REST API from 2016
Watch the project discussion meeting recording. It summarizes the project and the first possible steps
Study the Open API specification, go through examples for other services
Explore ways to index the REST API endpoints in Jenkins and Stapler.
@ExportedBean annotations, and other methods from the Stapler framework.
See the video for the links.
Create an Open API specification for a Jenkins plugin with REST API, add it to the respective plugin repository
Contribute to documentation of Jenkins REST API, e.g. see the
_api.jelly files in the Jenkins Core and plugins
Javadoc Landing Page — While Javadoc isn’t Rest API, user experience concerns described in INFRA-1717 for Javadoc Landing Page could be re-considered when determining where to publish Rest API accordingly
OpenAPI specification details and automatic generators
Stapler (more info: https://github.com/jenkins-infra/jenkins.io/pull/2157#issuecomment-471230609)