Skip to main content

Dev Docs

Документація розробника є не від'ємною частиною проекту і міститься в git в папці docs-dev

docs-dev                    # документація розробника
docs                        # документація

https://apidocs.softpro.ua/ - Всі документації доступні за адресою. CDN Сервер https://apidocs.softpro.ua/dev-docs-vitepress/ - Еталон документації https://vitepress.dev/ - SSG Технологія публікації документації

💡 Tip

Створюється до розробки, а не після!!! І постійно оновлюється під час розробки Зміст: API, DB, VUE, Readme

Покрокове налаштування документації​

Vitepress-Fork​

Детальний опис в README.me репозиторія, на основі якого будемо робити форк - https://git.softpro.ua/docs/docs-starter

Запуск з 0​

1. Додаємо vitepress та пакети

# додаємо vitepress та пакети
npm add -D vitepress
npm i -D sass, vitepress-plugin-mermaid, vitepress-plugin-tabs

2. Ініціюємо документацію

npx vitepress init
# вказуємо папку docs-dev, додаємо команди в packcage.json

Alt text

3. Автоматично вигружаємо документація

Для роботи з API перш за все необхідно склонувати GIT проект dev.

git clone -b dev https://git.softpro.ua/project/dev.git

Після клонування GIT проекту dev необхідно додати його до конфіг файлу:

Details
{
  "project": [
    "help"
    "dev"
  ],
  "folder": "",
  "db": ""
}

Тут приклад Глеба або посилання

4. .gitignore додаємо

*/.vitepress/cache
*/.vitepress/dist

5. pipeline

docs-253:
  stage: doc
  tags:
    - germany
  variables:
    GIT_STRATEGY: none
  script:
    - cd /data/softpro/server/$CI_PROJECT_NAME  && git pull
    - npm i
    - npm run docs:build
    - rm -rf /data/softpro/apidocs/$CI_PROJECT_NAME
    - mkdir -p /data/softpro/apidocs/$CI_PROJECT_NAME
    - cp -R ./docs-dev/.vitepress/dist/* /data/softpro/apidocs/$CI_PROJECT_NAME
  when: manual

Увага вказана ручна публікація. Тому треба в git запускати руками задачу.

6. запуск


#запуск в режимі розробки
npm run docs:dev

#запуск зборки для публікації
npm run docs:build

7. .vitepress/config.js

правимо згідно еталону

export default defineConfig({
  base: '/cardinal/', // вказати назву проекту
})

8. .vitepress/theme

Скопіювати папку

API​

API приймає наступні параметри:


param: {
  query: {
    download: /^1$/,
    method: /get|post|put|delete|all/,
    nocache: /^1$/,
    format: /md|html/,
  }
}

  • download - завантаження у вигляді архіву / файлу
  • method - необхідний для навігації у списку API
  • nocache - вимкнення кешу при завантаженні
  • format - вибір формату вихідних файлів

Приклади​