Requirements

User stories

• As a user, I want to generate API documentation with minimal impact to the way I work.
• As a user, I want to find all of the necessary information about the services my server can provide me in one convenient location.
• As a user, I don't want to input the same information twice.
• As a manager, I want the capacity to require fully documented servlets for a successful build.

Custom Annotations

The SwagGen will use a standard format to work with the servlet classes used by Outreach. Each endpoint method (SELECT, GET, PUT, POST) provided by the API will follow a standard format (this is tentative):

@SwaggerGen( 
    url = "url" 
    method = "POST/GET/PUT/DELETE" 
    headers = {"key=description"} 
    queryParam = {"key=description"} 
    body = "json.scheme" (alt. Body.class) 
    responses = {int} 
    responseBody = "json.scheme" (alt. Body.class) 
)

Annotations properties can also be set at the class level to apply to all of the children methods (such as the URL, some headers, etc.). Class level properties can be overridden by method level ones.

The response and request body will be created using the json schema used to validate incoming and outgoing data structures. We can piggyback on the existing data present in theses schemas to ensure the swagger documentation for the request body and output data structs stay up to date. JSON schemas follow the following structure:

{
  "definitions": {},
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://example.com/root.json",
  "type": "object",
  "required": [
    "checked",
    "dimensions"
  ],
  "properties": {
    "checked": {
      "$id": "#/properties/checked",
      "type": "boolean"
    },
    "dimensions": {
      "$id": "#/properties/dimensions",
      "type": "object",
      "required": [
        "width",
        "height"
      ],
      "properties": {
        "width": {
          "$id": "#/properties/dimensions/properties/width",
          "type": "integer"
        },
        "height": {
          "$id": "#/properties/dimensions/properties/height",
          "type": "integer"
        }
      }
    }
  }
}

Swagger File:

• Expected query string parameters
• Expected headers
• Expected body
• Expected HTTP code responses
• Expected output
• Data format
• Data type values (Strings, Integers, Floats, Dates, Time, etc…)
  • Data format (XML, JSON, CSV)
• RESTful URL name
• Expected scheme
  • HTTP, HTTPS

Mission:

Bridge the gap between code and documentation, prevent stale documentation from occuring Goal:

Ease of use for the backend server team to use Documentation of Swagger File:

Could be one of the following or a combination of

• Configuration files
• Java Annotations