846: Generate static (offline) documentation for services' APIs

Test Case #:846

 

Test Case Name: Generate static (offline) documentation for services' APIs

System: OpenLMIS

Subsystem: exapmle, requisition, auth

Test case designed by: Lucyna Kwidzińska

Design Date:03.08.2016

Short description:

We are starting to define and document all APIs in RAML format. While we may utilize Swagger to generate a live interface to browse/execute the APIs, an offline version is needed for general publishing. Using a service's RAML, generate offline doc and publish as part of the build artifacts.

Acceptance

  • For each service existing today (example, requisition, auth), add a process that generate static documentation from the service's RAML file.
  • The doc should be an artifact of the Jenkins build
  • The publishing step as well as the file format may be heavily influenced by the ReadTheDocs setup, not yet started at the time of this writing. By default, look to HTML format.
  • We ultimately want to present all services' documentation in a single "bundle"

                                                                                                                                                   

Pre – conditions:

                                                                                                                                                                                                                                                       

 

 

Step

Action

Expected system response

Comment

1

    Launch gradle clean command into command-line (for every service: example, requisition and auth).

                                                                                                     

 Build successful status should be returned.  

                                               

2

Launch gradle build command into command-line (for every service: example, requisition and auth).

Build successful status should be returned.

 

3

Verify if the api-definition.html file is accessible on openlmis-example/build/resources/main.

 

 

4

Verify if the api-definition.html file is accessible on openlmis-requisition/build/resources/main.

 

 

5

Verify if the api-definition.html file is accessible on openlmis-auth/build/resources/main.

 

6

 

 

 

7

  

 

8

                                                 

 

 

 

Post – conditions:

OpenLMIS: the global initiative for powerful LMIS software