GSoD-Developing User Friendly Github Documentation for REST API

[ayesh (Ayeshmantha Perera)]

Hi @burke

I am Ayeshmantha Perera.Currently studying my Master in IT.I would like to involve in the GitHub Documentation for REST API project.

I found it interesting since it’s about api documentation and which am familiar with as a developer. And also I so a similar GSoC project which was carried out in 2017.And had a walk through as well.

GSOC 2017 - Improved REST API Documentation Project

Hi, I am Bhashinee Nirmali, an undergraduate of Faculty of Information Technology, University of Moratuwa. I am good at programming in java and web development. I am interested in the gsoc project “Improved REST API Documentation Project”. I have tried out the Swagger Editor and Swagger Codegen. It would be grateful if you can provide me more information on this project. Thanks and Regards Bhashinee

Improved REST API Documentation Project - Midterm - Demo

Here is a mini demo on what we have achieved up until the second evaluation. Project: Improved REST API Documentation Project Mentors: @bholagabbar @pascal @harsha89

GSoC 2017 - Improved REST API Documentation Project - Final Presentation

Our main objective was to improve the living documentation of the OpenMRS REST API, by improving its Swagger Specification and through improvements to how its Swagger Specification is being generated. All my code goes in the OpenMRS REST Web Services Module. For those who are not familiar, it will be useful to have a quick look: https://qa-refapp.openmrs.org/openmrs/module/webservices/rest/apiDocs.htm My GSoC Issues for the Summer Below are the issues we’ve been tackling over the summer. I’ll…

As a starting point am wondering what can be tasks for me to pick up and work on this.

[jwnasambu (Juliet Wamalwa)]

Have you had a chance of reading through this GSoD 2019 : Warm up practices for Technical Writers?

[ayesh (Ayeshmantha Perera)]

Hi @jwnasambu

Yes I went through the thread in order to get an idea.

[jwnasambu (Juliet Wamalwa)]

Application began yesterday. Hope you are working on your proposal.

[ayesh (Ayeshmantha Perera)]

Yes will be publishing the draft soon .Is there a separate tag in jira to identify the technicle documentaion tasks.

[jwnasambu (Juliet Wamalwa)]

Are you asking of the projects? if yes, there are the links.
https://wiki.openmrs.org/display/RES/GSoD+2019+Project+Idea+1%3A+Developing+User+Friendly+Github+Documentation+for+REST+API

https://wiki.openmrs.org/display/RES/GSoD+2019+Project+Idea+2%3A+Developing+sustainable+approaches+to+avoiding+entropy+in+OpenMRS+documentation

https://wiki.openmrs.org/display/RES/GSoD+2019+Project+Idea+3%3A+Review+and+Refactor+existing+Wiki+to+be+more+User+profile+driven

[ayesh (Ayeshmantha Perera)]

Hi @burke, @jwnasambu

I went through the project description as well.Since I already have worked with some of the endpoint when am contributing to reports module and core module and on the work am already doing.I have bit of knowledge on the swagger documentation of openMRS.

What I want to know is are we proceeding with making the swagger documentation more readable or we are proceeding with writing separate api documentation for all the endpoints

[jwnasambu (Juliet Wamalwa)]

@burke is the mentor of that project I think he is the best person to answer you.

[burke (Burke Mamlin)]

The ultimate goal is to have beautiful REST API documentation hosted alongside our Javadoc documentation at api.openmrs.org similar to what you see at developer.github.com/v3/. Having interactive examples interspersed within the text that run against the demo server would be even better.

Ideally, documentation would be coupled with code to avoid divergence/inconsistencies and editing it would be easy for developers as well as technical writers. Some thoughts on how this could be done:

• Manually write API documentation (e.g., in Markdown)
  • Pros: straightforward for technical writers and could be easy for devs to edit as well
  • Cons: lack of any coupling between docs & code increases chances for mismatch
• Introducing Markdown within Javadocs that could be programmatically turned into documentation.
  • Pros: tight coupling of documentation with code
  • Cons: might be harder for non-devs to contribute to documentation and harder to see the “big picture” to be consistent across the documentation, there would still likely be introductory or non-resource-specific documentation we’d want to include.
• Manually generate interactive examples from the code using Swagger and then intersperse documentation around the interactive examples.
  • Pros: likely easier for non-devs to manage documentation
  • Cons: looser coupling between code & documentation could reduce contributions from devs and lead to mismatch between docs & code
• Some combination of approaches (e.g., manually create intro & cross-cutting documentation for things like authentication and pull resource-specific documentation from Javadocs)
  • Pros: tight coupling of documentation with code where it matters most while allowing for easier organization and handling of non-resource-specific content like intro, auth, etc.
  • Cons: more moving pieces, might be harder for non-devs to contribute to resource-specific documentation

Given GSoD is about documentation, I think generating the text is most important – e.g., writing Markdown documentation introducing the API, covering authentication, and then for each resource with some (perhaps hidden) labelling that would make it easier to move the text into source code in the future if we went that direction.

The extent to which we can document using Swagger or a Swagger-friendly approach, the easier it would be to align this effort with exiting API documentation.

[atlcto (Patrick Childers)]

I was researching prettier API documentation for another project and found this list had most of the popular options:

List of swagger UI alternatives

[ayesh (Ayeshmantha Perera)]

Hi @burke

Yes.I am going though the swagger documentation which was introduced by this project [Improved REST API Documentation Project - Midterm - Demo](http://GSoC Project For API documentation)

I think we can improve the swagger documentation as well with more proper responses errors and also describing more about the attributes in the api calls.

I already worked on similar project and done swagger documentations as well.

And also as in the github api documentation we can host the api documentation with all method based api documentation as well.

[ayesh (Ayeshmantha Perera)]

@atlcto I think most of the options that you shared are based on swagger documentation and open api spec is swager 3.0.I am already working on a apache project to have support for openapi spec 3 (PR :- https://github.com/apache/juneau/pull/44).And as I mentioned before we have swagger in place so I hope theres no need to migrate for a new swagger like documentation if am right @burke

[gayanw]

If you’ve plans for supporting OpenAPI Spec 3, I also recommend that you update swagger core model classes to v3 as well.

swagger-api/swagger-core

[ayesh (Ayeshmantha Perera)]

hi @gayanw

Yes if that’s what we planning on doing on the documentation will start working on it as well.

[ayesh (Ayeshmantha Perera)]

Hi @burke

I found a librarywhich can be helpful to full fill what you mentioned.Having markdown documentation align with already existing swagger .

The best thing about this is it now supports the openapi spec 3 as well.So if you’re already thinking about migrating to openapi spec 3 as gayan mentioned I can work on the base class migration and have support for openapi spec 3 as well.Since am already working with openmrs I hope it will be possible for me to do that as well.

And when it comes to this library we can use our swagger.yml files as an input and generate markdown documentation

Demo :- http://swagger2markup.github.io/spring-swagger2markup-demo/1.1.0/#_sub_chapter Library :- https://github.com/Swagger2Markup/swagger2markup

So looking forward to hear from you.

[laurelmichaels]

Hi @ayesh

I’m a tech writer interested in contributing to OpenMRS.

Your POC that links manually generated markup docs (getting started, etc) with Swagger output for the reference doc looks good to me!

If I can be of assistance, please let me know.

[ayesh (Ayeshmantha Perera)]

Hi @laurelmichaels

I’m looking forward to work on Developing User friendly Github Documentation Rest API documentation with GSOD and yeah maybe it will be migrated to OpenAPI Spec 3 as well yeah let’s see will let you know if we need any assistance. Btw thank you for asking.

[laurelmichaels]

Hi @ayesh,

Thanks for your reply. Please keep me updated, as I am very interested in contributing to the “Developing User friendly Github Documentation Rest API” GSOD project.

cc: @burke

[ayesh (Ayeshmantha Perera)]

Hi @laurelmichaels Yes please if you found something useful please update me too am also intrested in contributing as tech writer in gsod for this project

[shafiq12 (shafiq aslam)]

hello ayesh, i can extend my services as technical writer in this project GSoD, Developing User friendly Github Documentation for REST API. please involve me in this project, if there is something i can contribute to. i am motivated to work on this project. i would appreciate reading from you. thanks ,