Skip to:

  1. Skip to Jira Navigation
  2. Skip to Side Navigation
  3. Skip to Main Content

Publish API docs for each service to ReadTheDocs

Description

We want the ReadTheDocs API documentation page to provide the docs for each OpenLMIS service API: referencedata, requisition, and auth (for now). We also want it to link to the Swagger UI in addition to just linking to the static HTML version.

Currently, the page seems to link to and i-frame only the Requisition API docs in static HTML format. It is using the HTML version from the latest build artifact from build.openlmis.org/.

The page should link to API docs for all 3 of the services we've built so far (referencedata, requisition, and auth). And we want it to also link off to the running Swagger UI from the latest builds for all 3. Those are at test.openlmis.org/.

We believe it will be too cluttered to have 3 i-frames on a single page. So please remove the i-frame entirely and just use external links to route users to the right versions.

Acceptance Criteria

  • The API documentation page in ReadTheDocs has the API docs for all 3 services in both formats: Swagger UI and static HTML.

Attachments

1

Confluence content

mentioned on

QAlity Plus - Test Management

Checklists

Activity

Show:
Josh Zamor
October 28, 2016 at 5:58 PM

Looks good. I mentioned in https://openlmis.atlassian.net/browse/OLMIS-1138#icft=OLMIS-1138 that at the same time a swagger "dependency solution" is being worked on, we should also apply this to the Notification service and publish live doc.

Moving to done.

Brandon Bowersox-Johnson
October 28, 2016 at 12:01 AM

I'm hoping you can take this quick review.

The two commits are: https://openlmis.atlassian.net/browse/OLMIS-1168?devStatusDetailDialog=repository
(Let me know if you prefer to use Fisheye for documentation edits.)

I believe all the acceptance criteria have now been met. Oddly, the Notification service does not seem to expose a public Swagger UI (see my comment immediately above), so that service only has Static API docs. But the primary 3 services all now have Swagger and static API docs on ReadTheDocs: http://openlmis.readthedocs.io/en/latest/api/index.html

Brandon Bowersox-Johnson
October 27, 2016 at 8:25 PM

Note: Notification service does not seem to offer a public view of the Swagger UI.

URLs like this give an authentication error:
http://test.openlmis.org/notification/index.html

Brandon Bowersox-Johnson
October 14, 2016 at 11:14 AM
(edited)

Please review this ticket and edit as needed or give your Architect blessing to it.

FYI, here are the Test URLs for Swagger for all 3 services:
http://test.openlmis.org/referencedata/index.html
http://test.openlmis.org/requisition/index.html
http://test.openlmis.org/auth/index.html
(once UAT environment is built/deployed, the corresponding URLs will work on UAT as well)

And here are the URLs for the static offline API documentation for all 3 services (latest build by Jenkins):
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

Done
Pinned fields
Click on the next to a field label to start pinning.

Details

Assignee

Reporter

Story Points

Sprint

None

Fix versions

Priority

Parent

Time Assistant

Created October 14, 2016 at 11:08 AM
Updated November 2, 2016 at 4:42 PM
Resolved October 28, 2016 at 5:58 PM