GSoD-Developing User Friendly Github Documentation for REST API

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.

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

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

1 Like

Hi @jwnasambu

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

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

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

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

1 Like

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 :slightly_smiling_face:

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

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.

3 Likes

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

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.

@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

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

1 Like

hi @gayanw

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

1 Like

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.

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.

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.

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

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 :crossed_fingers::grinning:

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 ,

1 Like