Skip to main content

Redocusaurus

Why do I need to read this?

This documentation is helpful for anyone editing documentation related to the Swagger API definitions. It is helpful to understand those concepts first before diving into this documentation.

The goal of this documentation is to allow engineers to read Swagger API documentation within the Docusaurus site locally.

Need help? Ask in Slack.

This documentation leverages multiple projects that could lead to confusing error messages and warnings. For help, please reach out in #c-documentation🔒 if you get stuck.

What is Redocusaurus?​

Redocusaurus is a preset for Docusaurus. See the packages documentation for more general information about Redocusaurus. The purpose of this documentation is to help MilMove developers understand how the preset is integrated into Docusaurus and how to work with it locally.

Redocusaurus configuration​

The presets for Docusaurus are set in the docusaurus.config.js file in the transcom/mymove-docs repository. See the official Docusaurus documentation on using presets for more general information.

How Docusaurus consumes Swagger documentation

The way transcom/mymove-docs uses this is by leveraging the raw GitHub URLs for the Yaml files found in transcom/mymove. This means the API documentation is in sync with the default branch for the transcom/mymove repository. This means that until your Swagger file changes are merged into the default branch of transcom/mymove you cannot view the changes in the transcom/mymove-docs repository neither locally nor on the published website.

You can see this in the ./docusaurus.config.js file under the presets named redocusaurus.

Working with local changes to Swagger files​

To view changes to the Swagger documentation locally with Docusaurus, you need to have both repositories cloned on your machine. While you will be working with two repositories, the actual commits associated with these changes will happen in the transcom/mymove repository and not in the trancom/mymove-docs repository.

The two repositories​

Updating the Docusaurus configuration​

Once you have these repositories cloned locally, you will need to edit the documentation.config.js file to have the local copy of compiled Swagger files rather than pointing to the raw GitHub URL for the default branch.

The Git patch below shows what these changes would look like locally. The important thing to consider here is the location of the Swagger specification. In the example below, it is relative to the transcom/mymove-docs repository.

Updates to specification paths
diff --git a/docusaurus.config.js b/docusaurus.config.js
index 697ffef..30fdcc4 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -144,11 +144,11 @@ module.exports = {
       {
         specs: [
           {
-            spec: 'https://raw.githubusercontent.com/transcom/mymove/main/swagger/prime.yaml',
+            spec: '../mymove/swagger/prime.yaml',
             routePath: '/api/prime',
           },
           {
-            spec: 'https://raw.githubusercontent.com/transcom/mymove/main/swagger/support.yaml',
+            spec: '../mymove/swagger/support.yaml',
             routePath: '/api/support',
           },
         ],
About the diff output above

Due to edits to the docusaurus.config.js file since this documentation was written. The above diff is for illustrative purposes only and will not apply cleanly to the transcom/mymove repository.

Viewing changes in local Docusaurus​

Now that you have updated the docusaurus.config.js with the changes mentioned above, you will need to edit Swagger files found in transcom/mymove under swagger-def/ and then run the make swagger_generate command in order for them to show up in Docusaurus.

You will have to repeat this section for every change to the Swagger files. Make sure you have the transcom/mymove-docs server running locally. Whenever there are changes to the trancom/mymove/swagger/*.yaml files mentioned above, Docusaurus will helpfully reload the page. Because of interconnectedness of different technology, you may have to run the make swagger_generate command more than once if the changes aren't being reflected in your local Docusaurus API page.

tip

To automate the rendering changes in Docusaurus use the following command within the transcom/mymove repository.

rg -t yaml -t md --files swagger-def | entr -c make server_generate

If you do not have rg installed, run a similar command using find.

{ find swagger-def -type f -name '*.yml' ; find swagger-def -type f -name '*.yaml' ; find swagger-def -type f -name '*.md' } | entr -c make server_generate

Undoing local configuration for Redocusaurus​

If the only changes that were made to docusaurus.config.js are related to the Redocusaurus, you can easily discard these changes using the following Git command in the terminal. Please make sure you do this after you've committed changes in transcom/mymove which are related to the Swagger documentation.

git checkout -- docusaurus.config.js