Contributing to Moov open source docs (part 2)
In Part 1 we covered how to update our README and GitHub Pages documentation. In this article, we’ll map out how to quickly and easily suggest changes to our API documentation.
As a reminder, the documentation for our open source projects is here to serve you, the community. We’re always interested in feedback from those using our open source libraries and incredibly thankful to anyone willing to contribute to them.
API documentation
While you’re reading through the API documentation and running across issues, you can make an edit very quickly. First, you need to grab the yaml file, which contains the documentation:
- Navigate to a project, for example, https://github.com/moov-io/api
- Click on the openapi.yaml file
- Click on the “Raw” button in the upper right corner
- Copy the URL of the raw .yaml file
Now you can open up a new tab and import this raw .yaml file into Swagger, an in-browser editor for working with .yaml files:
- Navigate to editor.swagger.io
- Click File > Import URL
- Paste the URL you copied of the raw yaml file and click “Ok”
Now you should see the Moov API docs appear in a split-screen in your browser, allowing you to see what your changes will look like immediately.
When you’ve made all the changes you like, you can now navigate back to GitHub and submit your edits for review.
- Copy the entirety of your edited yaml file from the Swagger editor
- Click the “Edit this file” button on GitHub
- Replace openapi.yaml text with your new version
- Add a commit message at the bottom of the page
- Select “Create a new branch for this commit”
- Click “Propose changes”
Once you’ve completed these steps, you will be redirected to the final stage, creating a new pull request with your changes. The only thing left to do is click the “Create pull request” button.
That’s it! A Moov developer will now be notified of your submission and provide feedback. You’ve successfully done your part in moving us all closer to a more inclusive and accessible financial system!
