Automatic Specification Generator for Jenkins REST API

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

Details

Background

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.

Project Details

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: http://localhost/rest/api/1.0. The plugins would have their own REST API path with a version number like: http://localhost/plugin/rest/api/1.0. 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:

Quick-start

  1. Watch the project discussion meeting recording. It summarizes the project and the first possible steps

  2. Study the Open API specification, go through examples for other services

  3. Explore ways to index the REST API endpoints in Jenkins and Stapler. It includes @Exported and @ExportedBean annotations, and other methods from the Stapler framework. See the video for the links.

Newbie-friendly issues

  • Jira Query

  • 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

Skills to improve/study

  • Java

  • REST API

  • OpenAPI specification details and automatic generators

  • Stapler http://stapler.kohsuke.org/ (more info:https://github.com/jenkins-infra/jenkins.io/pull/2157#issuecomment-471230609)

Potential Mentors

Project Links

Organization Links

> Go back to other GSoC 2020 project ideas