Generate static (offline) documentation for services' APIs
Description
Attachments
- 03 Aug 2016, 01:33 PM
- 03 Aug 2016, 01:33 PM
- 03 Aug 2016, 01:32 PM
- 03 Aug 2016, 01:30 PM
- 03 Aug 2016, 01:30 PM
- 03 Aug 2016, 01:30 PM
relates to
QAlity Plus - Test Management
Checklists
Activity
@Mary Jo Kochendorfer For the record, here are the URLs for the offline API documentation for all 3 services:
http://build.openlmis.org/job/OpenLMIS-referencedata-service/lastSuccessfulBuild/artifact/build/resources/main/api-definition.html
http://build.openlmis.org/job/OpenLMIS-requisition-service/lastSuccessfulBuild/artifact/build/resources/main/api-definition.html
http://build.openlmis.org/job/OpenLMIS-auth-service/lastSuccessfulBuild/artifact/build/resources/main/api-definition.html
@Lucyna Laska could you speak with @Brandon Bowersox-Johnson and @Paweł Gesek about if there is a way to easily show us the other services? Or at least let me know the links for the other services.
Hi @Mary Jo Kochendorfer. Yes, API generation happening by service. For now, the API documentation for every service is not placed in one spot. Like you mention - http://openlmis.readthedocs.io/en/latest/api/index.html is only showing the requisition APIs. As far as I know, you can't see there the APIs documentation for other services.
@Lucyna Laska is the API generation happening by service? Is there a way to see all the services in one spot or navigate between the services? Right now http://openlmis.readthedocs.io/en/latest/api/index.html is only showing the requisition APIs, not Auth. Please let me know.
Test process:
Steps for generating static documentation file from:
a) openlmis-example service;
Note: repo has been cloned, docker should be running. Then:
1. Launch gradle clean command into command-line.
2. Launch gradle build command into command-line.
3. Verify if the api-definition.html file is accessible on openlmis-example/build/resources/main.
b) openlmis-requisition service;
Note: repo has been cloned, docker should be running. Then:
1. Launch gradle clean command into command-line.
2. Launch gradle build command into command-line.
3. Verify if the api-definition.html file is accessible on openlmis-requisition/build/resources/main.
c) openlmis-auth service;
Note: repo has been cloned, docker should be running. Then:
1. Launch gradle clean command into command-line.
2. Launch gradle build command into command-line.
3. Verify if the api-definition.html file is accessible on openlmis-auth/build/resources/main.
Details
Details
Assignee
Lucyna LaskaReporter
Rich MagnusonStory Points
Original estimate
Time tracking
Sprint
Fix versions
Priority
Major
Time Assistant
Open Time Assistant
Time Assistant
As a dev/implementer/integrator, I want documentation on OpenLMIS' APIs.
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". Again, this will likely be governed by OLMIS-673, but this requirement is good to keep in mind
See https://openlmis.atlassian.net/browse/OLMIS-796#icft=OLMIS-796 and https://openlmis.atlassian.net/browse/OLMIS-673#icft=OLMIS-673 for related topics.