/
API Documentation (Swagger) via API Gateway

API Documentation (Swagger) via API Gateway

By Iso Bassey (Unlicensed)
Nov 04, 2019

MoSCoW Rating for Elara Release:

Must

Description

EA currently does not ship with any consolidated API documentation. When API documentation is required, it is provided manually by downloading the Swagger file for each API and providing them to developers.  The purpose of this requirement is to aggregate all swaggers into the API gateway and make them easily accessible to developers.

Business Case

  • Making Swagger files accessible via the API gateway will save time by eliminating the current manual process of having to download them individually before sharing.
  • Providing API documentation with EA builds will ensure that organisations better understand how to maximise the value of EA’s APIs.

Personas effected

  • Software Developers

User Story

As a Developer I would like to have API documentation so that It is easier to access information about how best to maximize the value of EA APIs

Functionality

Use Case Title:

Aggregate Swagger files

Description (GOAL)

Aggregate all API Swagger files for EA and make them accessible via the API gateway

Trigger

This feature is triggered when an EA build is deployed

Primary Actors (Personas)

Developer

Secondary Actors 

EA System

Stakeholders 

Technical Architect, Developer

Preconditions 

Swagger file exists for each API

Aggregating Swagger file (Swagger of Swaggers) exists

User has access to API gateway

Flow (Main success Scenario)

  1. User visits EA documentation endpoint
  2. User is redirected to authentication page
  3. User successfully authenticates
  4. User is redirected to Swagger of Swaggers

Alternative flows

None

Post-conditions 

Success End condition: 

Read only file aggregating all Swagger files (Swagger of Swaggers) is accessible via the API gateway

Swagger files for all APIs are accessible via the API gateway


Failure End condition:

 User is unable to successfully authenticate

Frequency 

Not applicable

Priority 



Non Functional Requirements


RefAreaMoSCoWRequirementComments

1

Error-handling


Ease with which the system can degrade gracefully if errors occur - eg does the entire system go down and lose data if the internet goes down


2

Legal and Regulatory

 

specific legal and regulatory requirements associated with the feature


3

Licensing


new/amended licensing requirements associated with the feature or with introduced 3rd party components)


4

Localizability

 

need to include localised features eg currency; date formats


5

Performance


ability to meet specific performance standards/requirements


6

Concurrency

 

Specific concurrency requirements


7

Resilience


ability to handle failure of an individual component within the system


8

Scalability

 

requirements to support increasing numbers of users/concurrency without incurring significant cost


9

Security

M

adherence to defined/specified customer/industry security standards

Read-only access to Swagger of Swaggers. Read-only means they can't change the swagger html or add notes to it etc. Nothing to stop them running commands if they are authenticated.

10

Storage

 

Specific storage requirements/considerations


11

Supportability

 

ease with which Support could/need to access logs etc to diagnose a problem


12

Test requirements


ease with which the functionality could/should be supported by automated testing


13

Training

 

specific training/installation/configuration documentation that is associated with this feature that need to be created/updated

 

14

User Experience


specific user experience requirements that would ensure the functionality is acceptable to customers eg can complete action within x clicks



Sign Off


Add label