# Documentation Update Workflow

## Introduction

The Enectiva has two documentation webs: one public API for a [Librarian](https://apidocs.enectiva.cz/) project and
a private API [Internals](https://internals-enectiva.apidog.io) for a mobile app development.

> As both are based on Apiary, the update workflow is the same

The only difference is the place where the documentation is stored.
For Librarian, it is in the `/docs` folder [in the current repository](https://git.enectiva.cz/enectiva/librarian/-/tree/master/docs),
for Internals it is in the `/docs/internals` folder in the [Enectiva repository](https://git.enectiva.cz/enectiva/enectiva/docs/internals).

## Workflow
> !!! WARN: The content from GL branches and the content from the Apidog web do not correspond to each other

### TL;DR:
- Developer: adds a new version of the exported documentation `Enectiva REST API - *.md` and `Enectiva REST API - *.json`
- Reviewer: reviews the changes of `Enectiva REST API - *.md` and update documentation in the Apidog web

For detailed instructions, see the [Update docs](#update-docs) and [Review changes](#review-changes) sections.

### Useful links:
- [Apidog web](https://app.apidog.com/) - modify the documentation using the web interface of Apidog
- [Markdown Live Preview](https://markdownlivepreview.com/) - Review the Markdown file using any tool you’re comfortable
with. If you use a JetBrains IDE, you can take advantage of the built-in Markdown preview tool
- [Apidog documentation](https://docs.apidog.com/) - the official Apidog documentation
- [Extended Markdown syntax in the Apidog](https://docs.apidog.com/markdown-documentations-1262996m0)
- [How to link to various pages or endpoints within Apidog?](https://docs.apidog.com/how-to-use-cards-to-link-to-various-pages-or-endpoints-within-apidog-820878m0)

### Update docs
1) Visit the [Apidog web](https://app.apidog.com/) to start working you have been added to the relevant project at
least with an `Editor` role.

2) In the left sidebar, choose the Energo team and then select the relevant project (Librarian or Internals)

![](img/1.png)

3) Erase the content of the Apidog's **develop** branch. The fastest way to do it is to delete a branch and create a
new one with the same name. Click on the `Manage Sprint Branches` -> Archive the **develop** branch -> Delete the
**develop** branch -> Create a new branch, name it **develop**

![](img/8.png)

4) Choose the **develop** branch

![](img/2.png)

5) The main branch contains the latest merged version of the documentation. To prepare a new version of the
documentation, download the latest `Enectiva REST API - *.Apidog.json` file from the **develop** branch of
**Energo/Librarian** GitLab repository. Visit `Settings` -> `Import` -> `Apidog` and overwrite content of the
**develop** branch with the content of the downloaded file (overwrite is the default behaviour for the import).

![](img/3.png)

6) Edit the documentation and save it. For adding or updating new endpoint you should use UI Apidog. In the image you can see
highlighted buttons you will definitely use.

- Description: The Apidog supports [extended Markdown syntax](https://docs.apidog.com/markdown-documentations-1262996m0).
If you want to add a link to an existing endpoint,
  [read here](https://docs.apidog.com/how-to-use-cards-to-link-to-various-pages-or-endpoints-within-apidog-820878m0)
  how to do it properly.
- **Requests**: use predefined Security Schemes or define your own.
- **Responses & Requests**: ensure that params have the right type, mark as optional or required, etc.
- **Responses**: add examples for each case, you probably have already written them as a part of the endpoint implementation
(tests).
- Feel free to use the whole Apidog features, read the [documentation](https://docs.apidog.com/) to learn more.

When you finish, save the changes.

![](img/4.png)

7) To prepare files for the review, visit `Settings` -> `Export` -> `Apidog` and export the **develop** branch as a
`Apidog json` and `Markdown` files. The first one will be used for overwriting the content of the **main** branch, the
second one will be used for the review. 

![](img/5.png)

8) In GitLab, replace files from your issue's branch with the downloaded ones, commit the changes and create a merge
request to the **master** branch.

![](img/6.png)

### Review changes

1) Open the merge request, you will see the changes for the `Enectiva REST API - *.md` and `Enectiva REST API - *.json`
files. JSON and Markdown files should contain the same changes. For the review, use the Markdown file, as it is easier
to read. The JSON is used for importing the changes into the Apidog and can contain some additional data.

Also, you can try to use the [Apidog web](https://app.apidog.com/) **develop** branch to review the changes, but it is not
guaranteed that the changes haven't been overwritten by another developer as a part of the update workflow for the other
issue. The source of truth is the JSON file.

1) If everything is fine, approve the merge request
2) After the merge in GitLab → in the Apidog, update the **main** branch of the **Energo/Librarian docs** project.

   1) Visit the [Apidog web](https://app.apidog.com/) to start working you have been added to the relevant project at
      least with an `Editor` role.
   
   2) In the left sidebar, choose the Energo team and then select the relevant project (Librarian or Internals)

      ![](img/1.png)
   
   3) Choose the **main** branch
   
      ![](img/6.png)
   
   4) The main branch should contain the most up-to-date version of the documentation. To prepare a new version of the
      documentation, download the latest `Enectiva REST API - *.Apidog.json` file from the **develop** branch of
      **Energo/Librarian** GitLab repository. Visit `Settings` -> `Import` -> `Apidog` and overwrite content of the
      **main** branch with the content of the downloaded file (overwrite is the default behaviour for the import)
   
      ![](img/7.png)