gchq / gchq/sleeper

Add ability to auto generate open api spec for rest-api

Open
#7,749 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Java
Stars
107
Forks
29
Avg merge
19h 46m
Merged PRs (30d)
141

Description

### User Story

As a user of Sleeper I want to be able to get an openapi.yaml file for interacting with the Sleeper rest-api
As a developer of Sleeper I want this openapi.yaml to be auto generated

### Description / Background

Work was started on this in 7446 but then split out into this ticket. A first pass was made which involved methods on the routes that would contain the information for the spec however it was felt in the review that it would be better to have an approach that requires less manual input and instead uses tags to handle this.

### Acceptance Criteria

**Given** I have updated the rest-api routes
**When** I run the generateDocumentation script
**Then** It updates the openapi.yaml

**Given** I have updated the rest-api routes
**And** I have not ran the generateDocumentation script
**When** I commit the code to the repo
**Then** The build fails asking me to run the generateDocumentation script

### Technical Notes / Implementation Details

Some research will be needed on how to get this to work with tags over manual written descriptions

Contributor guide

Open the contributing guide

Research direction

Review the work from issue 7446 and the current REST-api routes, then inspect the generateDocumentation script and openapi.yaml. Research how route tags can provide the specification with less manual input. Done means the script updates openapi.yaml and the build detects route changes when generation has not been run.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi
Domain
api, build-system, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.