yq

Free GitHub tool: read YAML values with yq A large YAML config file can be awkward to scan when you only need one setting. `yq` by Mike Farah reads and processes YAML (and several other formats) from the terminal. It is free and MIT licensed. On a Mac with Homebrew: `brew install yq`. If `config.yaml` contains `server:` followed by an indented `port: 3000`, run `yq ".server.port" config.yaml` to print `3000`. Reading a value does not change the file; `-i` is the separate in-place edit option. You need a YAML file and a terminal, but no account or paid API. Official repo and other install methods: mikefarah/yq

วิธี Migrate จาก Redocly ไปยัง Apidog โดยไม่สูญเสียเวิร์กโฟลว์ Docs-as-Code หากคุณใช้งาน developer portal บน Redocly คุณก็ทำงานในแบบที่ทีม API ส่วนใหญ่ต้องการอยู่แล้ว: openapi.yaml อยู่ใน Git, คู่มือเป็น Markdown, และการ push จะอัปเดตเอกสาร ความกลัวเมื่อเปลี่ยนเครื่องมือคือการสูญเสียลูปนั้นและต้องมาแก้ไขเอกสารด้วยมือในเว็บ UI {% cta apidog.com %} ลองใช้ Apidog วันนี้ {% endcta %} คุณไม่จำเป็นต้องทำเช่นนั้น Apidog Spec-first Mode เก็บ spec และ Markdown ของคุณไว้ใน repository เดียวกัน ซิงค์ทุกครั้งที่ push ผ่าน webhook และเผยแพร่ portal ที่มีคู่มือและ API reference ใน sidebar เดียวกัน คู่มือนี้จะพาคุณผ่านการย้าย รวมถึงส่วนหนึ่งที่ไม่สามารถย้ายโดยอัตโนมัติได้: เนื้อหาแบบยาวที่ผู้ใช้ Redocly หลายคนเก็บไว้ใน info.description และ tags[].description หากคุณยังเปรียบเทียบเครื่องมืออยู่ เริ่มจาก Apidog vs. Redocly หรือรายการ Redocly alternatives ที่กว้างขึ้น บทความนี้ถือว่าคุณเลือก Apidog แล้วและต้องการย้ายโดยไม่ทำให้ workflow เสียหาย สิ่งที่ถ่ายโอนได้และสิ่งที่ไม่ได้ เราทดสอบการย้ายนี้ด้วย spec ของ production จริง: OpenAPI 3.0.3, 62 operations ใน 13 tags โดยมีเนื้อหา getting-started, authentication และ integration ที่เขียนไว้ในฟิลด์ description ของ spec นี่คือสิ่งที่เกิดขึ้นเมื่อนำเข้า | รายการ | ผลลัพธ์ใน Apidog Spec-first Mode | | --- | --- | | Operations, paths, พารามิเตอร์ | นำเข้าครบถ้วน (62 จาก 62) | | สคีมาและ components | นำเข้าครบถ้วน | | รูปแบบความปลอดภัย (API key, bearer, OAuth2) | นำเข้าครบถ้วน | | แท็ก | กลายเป็นโฟลเดอร์ endpoint (13 จาก 13) | | การซิงค์ Git | Push ไปที่ repo, webhook อัปเดตโปรเจกต์ | | info.description | นำเข้า แต่ไม่ถูกเรนเดอร์เป็นหน้าคู่มือแยกต่างหาก | | tags[].description | นำเข้า แต่ไม่แสดงเป็นหน้าแนะนำหมวดหมู่โดยค่าเริ่มต้น | | ไฟล์ Markdown ใน repo | ซิงค์และเผยแพร่เป็นหน้าเอกสาร | API reference ย้ายมาโดยไม่ต้องแก้ไข ช่องว่างคือเนื้อหาเชิงบรรยาย ทำไมฟิลด์ description ของคุณจึงเรนเดอร์ไม่เหมือนเดิม Redoc ซึ่งเป็น renderer ที่อยู่เบื้องหลังเอกสารอ้างอิงของ Redocly มอง info.description เป็นมินิเอกสาร ทุกหัวข้อ Markdown ภายในจะกลายเป็นรายการใน sidebar ดังนั้นทีมจึงมักเขียนคู่มือ "Getting started" และ "Authentication" ทั้งหมดไว้ที่นั่น คำอธิบายแท็กจะเรนเดอร์เป็นข้อความแนะนำที่ด้านบนของแต่ละกลุ่มแท็ก นั่นเป็นธรรมเนียมของ Redoc ไม่ใช่ส่วนหนึ่งของ OpenAPI Specification สเปกกำหนดเพียง description เป็นสตริง CommonMark เท่านั้น Apidog เช่นเดียวกับ portal ส่วนใหญ่ เก็บคู่มือเป็นเอกสาร Markdown แยกต่างหาก และเก็บสเปกไว้สำหรับการอ้างอิง การเผยแพร่เริ่มต้นหลังนำเข้าจะแสดงเฉพาะ API reference โดยไม่มีคู่มือที่คุณเขียนไว้ในฟิลด์ description วิธีแก้คือการย้ายครั้งเดียว: ยกเนื้อหานั้นออกจาก YAML ไปยังไฟล์ Markdown ที่อยู่ข้าง ๆ หลังจากนั้น ทุกอย่างจะขับเคลื่อนด้วย Git ต่อไป โครงสร้าง repository เป้าหมาย นี่คือโครงสร้างที่เราตรวจสอบแล้ว: your-repo/ ├── openapi.yaml # source of truth for the API reference └── docs/ ├── getting-started.md ├── authentication.md └── embed-integration-guide.md !Recommended repository layout for a Git-driven Apidog developer portal: openapi.yaml at the root, guides in docs/ openapi.yaml ขับเคลื่อน API reference แต่ละไฟล์ใน docs/ จะกลายเป็นหน้าใน sidebar ของ portal รูปภาพที่อ้างอิงโดยไฟล์ Markdown เหล่านั้นสามารถอยู่ใน repo เดียวกันและซิงค์ไปด้วยกัน หากคุณใช้ sidebars.yaml ของ Redocly เพื่อจัดลำดับ navigation ให้เก็บไว้เป็นข้อมูลอ้างอิง คุณจะตั้งลำดับเดียวกันครั้งเดียวในการตั้งค่า docs site ของ Apidog การย้ายทีละขั้นตอน 1. ตรวจสอบสิ่งที่อยู่ภายในฟิลด์ description ของคุณ ก่อนย้ายสิ่งใด ดูว่ามีเนื้อหาอยู่ใน spec มากแค่ไหน ด้วย yq: # How long is the top-level description? yq '.info.description' openapi.yaml | wc -w # Which headings does it contain? Each one is a Redoc sidebar entry today. yq '.info.description' openapi.yaml | grep -E '^#{1,3} ' # Which tags carry a description? yq '.tags[] | select(.description != null) | .name' openapi.yaml รายการหัวข้อคือรายการไฟล์ docs/ ในอนาคตของคุณ ในการทดสอบของเรา info.description ถูกแยกออกเป็นไฟล์ Markdown สองไฟล์ และคำอธิบายแท็กกลายเป็นหน้าแนะนำต่อโฟลเดอร์บวกกับไฟล์ Markdown เพิ่มอีกหนึ่งไฟล์ 2. แยก info.description เป็นไฟล์ Markdown คัดลอกแต่ละส่วนระดับบนสุดไปยังไฟล์ของตัวเองภายใต้ docs/ เก็บหัวข้อ ตัวอย่างโค้ด และลิงก์ไว้ จากนั้นย่อ info.description ใน spec ให้เหลือเพียงสรุปหนึ่งย่อหน้า เพื่อให้เนื้อหาอยู่ในที่เดียวเท่านั้น ระวังคุณสมบัติเฉพาะของ Redoc สองอย่างขณะคัดลอก: - <SecurityDefinitions /> และแท็ก Redoc ที่คล้ายกันจะไม่เรนเดอร์นอก Redoc แทนที่ด้วยส่วนที่เขียนสั้น ๆ ซึ่งลิงก์ไปยัง security schemes ในการอ้างอิง - ลิงก์เช่น #tag/Payments ชี้ไปยัง anchor ของ Redoc อัปเดตเป็น URL ของเอกสารหรือโฟลเดอร์ Apidog ที่ตรงกันหลังการเผยแพร่ครั้งแรก 3. เชื่อมต่อ repository ใน Spec-first Mode สร้างโปรเจกต์ใน Spec-first Mode เชื่อมต่อ repository ของคุณ (GitHub, GitLab, Azure DevOps หรือ Bitbucket) ชี้ไปที่ openapi.yaml และโฟลเดอร์ docs/ และติดตั้ง webhook จากนั้นเป็นต้นไป การ push ไปยังแบรนช์ที่ติดตามจะอัปเดตโปรเจกต์ !Creating a Spec-first Mode project in Apidog: connect a GitHub repository, pick the main branch and tick Install Webhook หลังการซิงค์ครั้งแรก workspace Specs จะแสดง spec และส่วนที่เหลือของ repository แท็บ APIs แสดงรายการ operations ที่แยกวิเคราะห์จาก openapi.yaml Docs เก็บหน้า Markdown ของคุณ และ All files สะท้อน repo !The Specs workspace in Apidog after a Git sync, with APIs, Docs and All files tabs and a Synced just now status webhook คือสิ่งที่ทำให้สิ่งนี้เป็น workflow แบบ docs-as-code หากไม่มีคุณจะต้องทริกเกอร์การซิงค์ด้วยมือ สำหรับทบทวนว่าทำไมสิ่งนี้จึงสำคัญ ดูคู่มือของเราเกี่ยวกับ docs as code 4. เผยแพร่ docs site และตั้งค่า navigation เผยแพร่ docs site จากโปรเจกต์และจัดเรียง sidebar ลำดับที่ผู้ใช้ Redocly ส่วนใหญ่ต้องการ และเป็นลำดับที่เราทำซ้ำได้คือ: 1. เริ่มต้นใช้งาน 2. การรับรองความถูกต้อง 3. คู่มือการรวมระบบ 4. API Reference (โฟลเดอร์ endpoint จากแท็กของคุณ) หน้า Markdown และโฟลเดอร์ API ผสมกันได้อย่างอิสระในแผนผังเดียว ดังนั้นคุณจึงสามารถจับคู่ sidebar Redocly ปัจจุบันของคุณได้อย่างใกล้เคียง 5. เพิ่มโดเมนที่กำหนดเอง ชี้ CNAME เช่น developers.example.com ไปที่ docs site โดเมนที่กำหนดเองมีให้ใช้ในแผนฟรี ให้ coding agent ของคุณย้ายคำอธิบายแท็กด้วย Apidog CLI คำอธิบายแท็กเป็นส่วนที่น่าเบื่อที่สุด สิบสามแท็กหมายถึงงานคัดลอกวางสิบสามงาน และคุณจะทำซ้ำทุกครั้งที่คำอธิบายแท็กเปลี่ยนระหว่างการเปลี่ยนผ่าน มอบหมายให้ coding agent ของคุณแทน Apidog CLI ให้ Claude Code, Codex, Cursor หรือ agent ใน terminal ใด ๆ เข้าถึงโปรเจกต์ของคุณในรูปแบบ JSON ที่มีโครงสร้าง รวมถึงโฟลเดอร์ endpoint ตั้งค่าครั้งเดียว: npm install -g apidog-cli@latest apidog auth login --with-token <YOUR_ACCESS_TOKEN> npx -y skills add https://apidog.com บรรทัดสุดท้ายติดตั้ง Apidog skill เพื่อให้ agent ของคุณรู้คำสั่งโดยไม่ต้องเดา คู่มือการติดตั้ง ครอบคลุมโทเค็นและการปรับใช้แบบส่วนตัว จากนั้นให้ prompt หนึ่งอย่างกับ agent ของคุณ: > อ่าน openapi.yaml สำหรับทุกแท็กที่มี description ให้ค้นหาโฟลเดอร์ endpoint ที่ตรงกันในโปรเจกต์ Apidog <PROJECT_ID> และตั้งค่า description ของโฟลเดอร์นั้นเป็น description ของแท็ก ตรวจสอบ payload แต่ละอันด้วย apidog cli-schema validate folder-update ก่อนเขียน แสดงรายการโฟลเดอร์ที่คุณเปลี่ยน นี่คือสิ่งที่ agent เรียกใช้: # Find the folder IDs that correspond to your tags apidog folder list --project <PROJECT_ID> --type endpoint # Check the payload shape instead of guessing it apidog cli-schema get folder-update # For each tag: write {"description": "..."} to a file, validate, then update apidog cli-schema validate folder-update --file ./payments-folder.json apidog folder update <FOLDER_ID> --project <PROJECT_ID> --type endpoint \ --file ./payments-folder.json !apidog cli-schema get folder-update shows the folder description field the agent writes to สคีมา folder-update ยอมรับ name, parentId และ description และ description รองรับบนโฟลเดอร์ endpoint และ test-scenario สำหรับคู่มือที่ไม่ได้เป็นของแท็กเดียว agent สามารถใช้ apidog doc list และ apidog doc create ในลักษณะเดียวกันได้ หลังจากอ่าน apidog cli-schema get doc-create หากต้องการแสดงคำแนะนำของโฟลเดอร์บนไซต์ที่เผยแพร่ ให้ตั้งค่า Folder Contents Displaying Setting ในการตั้งค่าโฟลเดอร์ภายใต้ Documentation Settings after Publication !Apidog folder settings: Documentation Settings after Publication, with Directory Tree Display Style and Folder Contents Displaying Setting ข้อควรระวังอย่างตรงไปตรงมา: การแสดงคำอธิบายแท็กเป็นหน้าแนะนำต่อหมวดหมู่ได้ผล แต่มันอาศัยเส้นทางที่เอกสารน้อยกว่า ทดสอบกับสองสามโฟลเดอร์ใน workspace ของคุณก่อนที่จะพึ่งพามันสำหรับทั้งหมด สำหรับงาน spec ที่ขับเคลื่อนด้วย agent เพิ่มเติม ดู การใช้ Apidog CLI ใน Claude Code และ การให้ agent อัปเดต API spec ของคุณ สิ่งที่อยู่นอก Git โปรเจกต์ Spec-first เก็บ API และ Markdown ของคุณไว้ใน Git การตั้งค่า portal บางอย่างอยู่ในอินเทอร์เฟซ Apidog และไม่ได้ถูกควบคุมเวอร์ชัน: | การตั้งค่า | ที่อยู่ | | --- | --- | | openapi.yaml (endpoints, สคีมา, ความปลอดภัย) | Git | | หน้าคู่มือใน docs/ | Git | | การเผยแพร่ docs site | อินเทอร์เฟซ Apidog | | ลำดับ sidebar และ navigation | อินเทอร์เฟซ Apidog | | การตั้งค่าการแสดงคำแนะนำโฟลเดอร์ | อินเทอร์เฟซ Apidog | | โดเมนที่กำหนดเอง | อินเทอร์เฟซ Apidog และ DNS ของคุณ | สิ่งเหล่านี้เป็นการตั้งค่าครั้งเดียว คุณจะแตะต้องเมื่อเพิ่มส่วนระดับบนสุดใหม่ ไม่ใช่ทุกครั้งที่เนื้อหาเปลี่ยน Redocly เก็บสิ่งเหล่านี้ไว้มากกว่าใน redocly.yaml และ sidebars.yaml ดังนั้นหากคุณตรวจสอบการเปลี่ยนแปลง navigation ใน pull request วันนี้ ให้วางแผนว่าสิ่งนั้นจะย้ายไปใน UI แผนและราคา การตั้งค่าที่อธิบายที่นี่เหมาะกับแผนฟรี รวมโดเมนที่กำหนดเอง แผนฟรีครอบคลุมสมาชิกทีมสูงสุด 4 คน แผนแบบชำระเงินเพิ่มสิ่งต่าง ๆ เช่น หลาย documentation site ต่อโปรเจกต์ และการควบคุมการมองเห็นแบบกำหนดเอง ตรวจสอบ ราคา Apidog สำหรับขีดจำกัดปัจจุบัน Redocly vs. Apidog หลังการย้าย | | Redocly | Apidog Spec-first Mode | | --- | --- | --- | | Spec ใน Git | ใช่ | ใช่ | | คู่มือเป็น Markdown ใน Git | ใช่ | ใช่ | | ซิงค์อัตโนมัติเมื่อ push | ใช่ | ใช่ ผ่าน webhook | | คู่มือภายใน info.description | เรนเดอร์เป็นส่วนใน sidebar | ย้ายไปเป็นไฟล์ Markdown | | การตั้งค่า navigation | sidebars.yaml ใน Git | อินเทอร์เฟซ Apidog | | การทดสอบ API, mocking, debugging | เครื่องมือแยก | โปรเจกต์เดียวกัน | | การเข้าถึงของ agent ผ่าน CLI | Redocly CLI (lint, bundle, build) | Apidog CLI (อ่านและเขียนทรัพยากรโปรเจกต์) | การแลกเปลี่ยนนั้นง่าย คุณสูญเสีย navigation ที่กำหนดด้วย YAML คุณได้การทดสอบ, mocking และ CLI ที่เป็นมิตรกับ agent บน spec เดียวกันกับที่เอกสารของคุณมาจาก สำหรับการเปรียบเทียบ CLI ต่อ CLI อ่าน Apidog CLI vs Redocly CLI คำถามที่พบบ่อย URL ที่โฮสต์บน Redocly ของฉันจะยังใช้งานได้หรือไม่? ไม่โดยอัตโนมัติ path ของหน้าเปลี่ยน หาก portal เก่าของคุณมี URL คู่มือที่มีทราฟฟิกสูง ให้เพิ่มการเปลี่ยนเส้นทางที่ DNS หรือ proxy layer สำหรับหน้าหลักหลังจากคุณเปลี่ยนโดเมน ฉันต้องเขียน OpenAPI spec ใหม่หรือไม่? ไม่ สเปกนำเข้าได้ตามที่เป็น คุณเพียงย้ายเนื้อหาเชิงบรรยายออกจาก info.description และ tags[].description ไปยังไฟล์ Markdown ฉันเก็บ x-tagGroups ไว้ได้หรือไม่? ใช้โฟลเดอร์สำหรับการจัดกลุ่มแทน แต่ละแท็กจะกลายเป็นโฟลเดอร์ และคุณสามารถซ้อนโฟลเดอร์เพื่อจำลองกลุ่มแท็กของคุณได้ สิ่งนี้เปรียบเทียบกับการย้ายจาก Stoplight อย่างไร? รูปแบบคล้ายกัน: spec ใน Git, Markdown ข้าง ๆ, การซิงค์ผ่าน webhook ดู วิธี migrate จาก Stoplight ไปยัง Apidog หากคุณใช้ทั้งสองเครื่องมือ จะเกิดอะไรขึ้นหากขั้นตอนหนึ่งทำงานแตกต่างใน workspace ของฉัน? ผลลัพธ์ของเรามาจากสภาพแวดล้อมทดสอบ ให้รันการนำเข้าซ้ำบนแบรนช์ก่อน และเปรียบเทียบ portal ที่เผยแพร่กับอันปัจจุบันของคุณก่อนเปลี่ยน DNS ย้ายในหนึ่งบ่าย การย้ายจาก Redocly ไป Apidog ส่วนใหญ่เป็นการย้ายเนื้อหา spec ของคุณนำเข้าได้ตามที่เป็น คู่มือของคุณย้ายออกจากฟิลด์ description ไปยังโฟลเดอร์ docs/ ครั้งเดียว webhook จะทำให้ทุกอย่างซิงค์กันหลังจากนั้น ให้ agent ของคุณจัดการงานซ้ำ ๆ อย่างคำอธิบายแท็กด้วย Apidog CLI และใช้เวลาของคุณตรวจสอบ portal ที่เผยแพร่ทีละหน้า ดาวน์โหลด Apidog และเชื่อมต่อ repo ของคุณกับ Spec-first Mode เพื่อเริ่มการย้าย {% embed youtube.com %}

Cómo migrar de Redocly a Apidog sin perder tu flujo de trabajo Docs-as-Code Si gestionas tu portal para desarrolladores con Redocly, ya trabajas como la mayoría de los equipos de API quieren: openapi.yaml vive en Git, las guías están en Markdown y un push actualiza la documentación. El miedo al cambiar de herramienta es perder ese ciclo y acabar editando la documentación a mano en una interfaz web. {% cta apidog.com %} Prueba Apidog hoy {% endcta %} No tienes por qué hacerlo. El modo Spec-first de Apidog mantiene tu spec y tu Markdown en el mismo repositorio, sincroniza en cada push mediante un webhook y publica un portal con guías y una referencia de API en una sola barra lateral. Esta guía recorre la migración, incluida la única parte que no se transfiere automáticamente: el contenido extenso que muchos usuarios de Redocly guardan dentro de info.description y tags[].description. Si todavía estás comparando herramientas, empieza por Apidog vs. Redocly o por la lista más amplia de alternativas a Redocly. Este artículo asume que ya has elegido Apidog y quieres hacer el cambio sin romper tu flujo de trabajo. Qué se transfiere y qué no Probamos esta migración con una spec de producción real: OpenAPI 3.0.3, 62 operaciones repartidas en 13 tags, con contenido de primeros pasos, autenticación e integración escrito en los campos description de la spec. Esto es lo que ocurrió al importar: | Elemento | Resultado en el modo Spec-first de Apidog | | --- | --- | | Operaciones, rutas, parámetros | Importadas intactas (62 de 62) | | Esquemas y components | Importados intactos | | Esquemas de seguridad (API key, bearer, OAuth2) | Importados intactos | | Tags | Se convirtieron en carpetas de endpoints (13 de 13) | | Sincronización con Git | Push al repositorio, el webhook actualiza el proyecto | | info.description | Importado, pero no se renderiza como páginas de guía independientes | | tags[].description | Importado, pero no se muestra como páginas de introducción de categoría de forma predeterminada | | Archivos Markdown en el repositorio | Sincronizados y publicados como páginas de documentación | La referencia de la API se transfiere sin cambios. El vacío está en el contenido narrativo. Por qué tus campos description no se renderizan igual Redoc, el renderizador que hay detrás de la documentación de referencia de Redocly, trata info.description como un mini documento. Cada encabezado Markdown que contiene se convierte en una entrada de la barra lateral, así que los equipos suelen escribir ahí todas sus guías de «Primeros pasos» y «Autenticación». Las descripciones de los tags se renderizan como texto de introducción en la parte superior de cada grupo de tags. Eso es una convención de Redoc, no forma parte de la especificación OpenAPI. La especificación solo define description como una cadena CommonMark. Apidog, como la mayoría de los portales, mantiene las guías como documentos Markdown independientes y reserva la spec para la referencia. Una publicación predeterminada después de la importación muestra únicamente la referencia de la API, sin las guías que escribiste en los campos description. La solución es un traslado único: saca ese contenido del YAML y llévalo a archivos Markdown junto a él. A partir de ahí, todo sigue funcionando con Git. La estructura del repositorio de destino Esta es la estructura que validamos: your-repo/ ├── openapi.yaml # source of truth for the API reference └── docs/ ├── getting-started.md ├── authentication.md └── embed-integration-guide.md !Estructura de repositorio recomendada para un portal de desarrolladores de Apidog impulsado por Git: openapi.yaml en la raíz, guías en docs/ openapi.yaml controla la referencia de la API. Cada archivo de docs/ se convierte en una página de la barra lateral del portal. Las imágenes a las que hacen referencia esos archivos Markdown pueden vivir en el mismo repositorio y sincronizarse con ellos. Si usabas el sidebars.yaml de Redocly para ordenar tu navegación, consérvalo como referencia. Establecerás ese mismo orden una vez en la configuración del sitio de documentación de Apidog. Migración paso a paso 1. Audita qué hay dentro de tus campos description Antes de mover nada, comprueba cuánto contenido hay en la spec. Con yq: # How long is the top-level description? yq '.info.description' openapi.yaml | wc -w # Which headings does it contain? Each one is a Redoc sidebar entry today. yq '.info.description' openapi.yaml | grep -E '^#{1,3} ' # Which tags carry a description? yq '.tags[] | select(.description != null) | .name' openapi.yaml La lista de encabezados es tu futura lista de archivos en docs/. En nuestra prueba, info.description se dividió en dos archivos Markdown, y las descripciones de los tags se convirtieron en páginas de introducción por carpeta más un archivo Markdown adicional. 2. Divide info.description en archivos Markdown Copia cada sección de nivel superior a su propio archivo dentro de docs/. Conserva los encabezados, los ejemplos de código y los enlaces. Después, reduce info.description en la spec a un resumen de un párrafo, para que el contenido viva en un solo lugar. Ojo con dos características específicas de Redoc mientras copias: - <SecurityDefinitions /> y otros tags similares de Redoc no se renderizan fuera de Redoc. Sustitúyelos por una breve sección escrita que enlace a los esquemas de seguridad de la referencia. - Los enlaces como #tag/Payments apuntan a anclas de Redoc. Actualízalos a las URL del documento o la carpeta correspondientes de Apidog después de la primera publicación. 3. Conecta el repositorio en el modo Spec-first Crea un proyecto en el modo Spec-first, conecta tu repositorio (GitHub, GitLab, Azure DevOps o Bitbucket), apúntalo a openapi.yaml y a la carpeta docs/, e instala el webhook. A partir de entonces, un push a la rama monitorizada actualiza el proyecto. !Creación de un proyecto en modo Spec-first en Apidog: conectar un repositorio de GitHub, elegir la rama principal y marcar Install Webhook Tras la primera sincronización, el espacio de trabajo Specs muestra tu spec y el resto del repositorio. La pestaña APIs lista las operaciones analizadas de openapi.yaml, Docs contiene tus páginas Markdown y All files refleja el repositorio. !El espacio de trabajo Specs en Apidog tras una sincronización con Git, con las pestañas APIs, Docs y All files y el estado Synced just now El webhook es lo que mantiene esto como un flujo de trabajo de documentación como código. Sin él, tendrías que lanzar las sincronizaciones a mano. Si quieres recordar por qué importa esto, consulta nuestra guía sobre docs as code. 4. Publica el sitio de documentación y configura la navegación Publica un sitio de documentación desde el proyecto y organiza la barra lateral. El orden que quieren la mayoría de los usuarios de Redocly, y el que reprodujimos, es: 1. Primeros pasos 2. Autenticación 3. Guías de integración 4. Referencia de la API (las carpetas de endpoints de tus tags) Las páginas Markdown y las carpetas de API se mezclan libremente en un mismo árbol, así que puedes replicar de cerca tu barra lateral actual de Redocly. 5. Añade tu dominio personalizado Apunta un CNAME como developers.example.com al sitio de documentación. Los dominios personalizados están disponibles en el plan gratuito. Deja que tu agente de programación migre las descripciones de los tags con Apidog CLI Las descripciones de los tags son la parte más tediosa. Trece tags significan trece tareas de copiar y pegar, y tendrás que rehacerlas cada vez que cambie una descripción de tag durante la transición. Dáselo a tu agente de programación. Apidog CLI da a Claude Code, Codex, Cursor o cualquier agente de terminal acceso JSON estructurado a tu proyecto, incluidas las carpetas de endpoints. Configúralo una vez: npm install -g apidog-cli@latest apidog auth login --with-token <YOUR_ACCESS_TOKEN> npx -y skills add https://apidog.com La última línea instala la skill de Apidog para que tu agente conozca los comandos sin tener que adivinarlos. La guía de instalación cubre los tokens y los despliegues privados. Después, dale a tu agente un solo [REDACTED PROMPT] descripción del tag. Valida cada payload con apidog cli-schema validate folder-update antes de escribir. Muéstrame la lista de carpetas que has cambiado. Esto es lo que ejecuta el agente: # Find the folder IDs that correspond to your tags apidog folder list --project <PROJECT_ID> --type endpoint # Check the payload shape instead of guessing it apidog cli-schema get folder-update # For each tag: write {"description": "..."} to a file, validate, then update apidog cli-schema validate folder-update --file ./payments-folder.json apidog folder update <FOLDER_ID> --project <PROJECT_ID> --type endpoint \ --file ./payments-folder.json !apidog cli-schema get folder-update muestra el campo de descripción de carpeta en el que escribe el agente El esquema folder-update acepta name, parentId y description, y description es compatible con las carpetas de endpoints y de escenarios de prueba. Para las guías que no pertenecen a un único tag, el agente puede usar apidog doc list y apidog doc create de la misma forma, después de leer apidog cli-schema get doc-create. Para mostrar la introducción de una carpeta en el sitio publicado, configura Folder Contents Displaying Setting en los ajustes de la carpeta, dentro de Documentation Settings after Publication. !Ajustes de carpeta en Apidog: Documentation Settings after Publication, con Directory Tree Display Style y Folder Contents Displaying Setting Una advertencia honesta: mostrar las descripciones de los tags como páginas de introducción por categoría funciona, pero se apoya en un camino menos documentado. Pruébalo en dos o tres carpetas de tu propio espacio de trabajo antes de depender de ello para todas. Para más trabajo de spec impulsado por agentes, consulta usar Apidog CLI en Claude Code y dejar que un agente actualice tu spec de API. Qué queda fuera de Git Un proyecto Spec-first mantiene tu API y tu Markdown en Git. Algunos ajustes del portal viven en la interfaz de Apidog y no están bajo control de versiones: | Ajuste | Dónde vive | | --- | --- | | openapi.yaml (endpoints, esquemas, seguridad) | Git | | Páginas de guía en docs/ | Git | | Publicación del sitio de documentación | Interfaz de Apidog | | Orden de la barra lateral y navegación | Interfaz de Apidog | | Ajustes de visualización de la introducción de carpeta | Interfaz de Apidog | | Dominio personalizado | Interfaz de Apidog y tu DNS | Son elementos que se configuran una sola vez. Los tocas cuando añades una nueva sección de nivel superior, no en cada cambio de contenido. Redocly guarda más de esto en redocly.yaml y sidebars.yaml, así que si hoy revisas los cambios de navegación en pull requests, ten previsto que eso pase a la interfaz. Plan y precios La configuración descrita aquí cabe en el plan gratuito, incluido el dominio personalizado. El plan gratuito admite hasta 4 miembros del equipo. Los planes de pago añaden cosas como varios sitios de documentación por proyecto y controles de visibilidad personalizados. Consulta los precios de Apidog para conocer los límites actuales. Redocly vs. Apidog después de la migración | | Redocly | Modo Spec-first de Apidog | | --- | --- | --- | | Spec en Git | Sí | Sí | | Guías en Markdown en Git | Sí | Sí | | Sincronización automática al hacer push | Sí | Sí, mediante webhook | | Guías dentro de info.description | Se renderizan como secciones de la barra lateral | Hay que moverlas a archivos Markdown | | Configuración de navegación | sidebars.yaml en Git | Interfaz de Apidog | | Pruebas, mocking y depuración de API | Herramientas separadas | El mismo proyecto | | Acceso de agentes vía CLI | Redocly CLI (lint, bundle, build) | Apidog CLI (leer y escribir recursos del proyecto) | El intercambio es sencillo. Pierdes la navegación definida en YAML. Ganas pruebas, mocking y una CLI amigable para agentes sobre la misma spec de la que salen tus documentos. Para un análisis CLI por CLI, lee Apidog CLI vs Redocly CLI. FAQ ¿Seguirán funcionando mis URL alojadas en Redocly? No de forma automática. Las rutas de las páginas cambian. Si tu antiguo portal tenía URL de guías con mucho tráfico, añade redirecciones en tu capa de DNS o proxy para las páginas principales después de cambiar el dominio. ¿Tengo que reescribir mi spec de OpenAPI? No. La spec se importa tal cual. Solo mueves el contenido narrativo de info.description y tags[].description a archivos Markdown. ¿Puedo conservar x-tagGroups? Usa carpetas para agrupar en su lugar. Cada tag se convierte en una carpeta, y puedes anidar carpetas para reproducir tus grupos de tags. ¿Cómo se compara esto con migrar desde Stoplight? La forma es similar: spec en Git, Markdown al lado, sincronización por webhook. Consulta cómo migrar de Stoplight a Apidog si usas ambas herramientas. ¿Y si algún paso se comporta de forma distinta en mi espacio de trabajo? Nuestros resultados provienen de un entorno de prueba. Vuelve a ejecutar la importación primero en una rama y compara el portal publicado con el actual antes de cambiar el DNS. Haz el cambio en una tarde Una migración de Redocly a Apidog es, sobre todo, un traslado de contenido. Tu spec se importa tal cual. Tus guías salen de los campos description a una carpeta docs/ una sola vez. A partir de ahí, un webhook lo mantiene todo sincronizado. Deja que tu agente se encargue del trabajo repetitivo de las descripciones de tags con Apidog CLI, y dedica tu tiempo a revisar el portal publicado página por página. Descarga Apidog y conecta tu repositorio al modo Spec-first para empezar la migración. {% embed youtube.com %}

Docs-as-Code 워크플로우를 유지하면서 Redocly에서 Apidog로 마이그레이션하는 방법 Redocly에서 개발자 포털을 운영하고 있다면, 이미 대부분의 API 팀이 원하는 방식으로 일하고 있는 것입니다. openapi.yaml은 Git에 있고, 가이드는 Markdown이며, 푸시하면 문서가 업데이트됩니다. 도구를 바꿀 때 두려운 점은 바로 그 흐름을 잃고 웹 UI에서 문서를 손으로 편집하게 되는 것입니다. {% cta apidog.com %} 지금 Apidog 사용해 보기 {% endcta %} 그럴 필요는 없습니다. Apidog Spec-first Mode는 스펙과 Markdown을 같은 저장소에 유지하고, 웹훅을 통해 푸시할 때마다 동기화하며, 가이드와 API 레퍼런스를 하나의 사이드바에 담은 포털을 게시합니다. 이 가이드는 마이그레이션 과정을 단계별로 안내하며, 자동으로 넘어가지 않는 한 가지 부분, 즉 많은 Redocly 사용자가 info.description과 tags[].description 안에 보관하는 장문 콘텐츠까지 다룹니다. 아직 도구를 비교 중이라면 Apidog vs. Redocly 또는 더 폭넓은 Redocly 대안 목록부터 시작하세요. 이 글은 Apidog를 선택했고 워크플로를 깨뜨리지 않고 이전하고 싶다는 전제로 작성되었습니다. 무엇이 그대로 넘어오고 무엇이 그렇지 않은가 우리는 실제 프로덕션 스펙으로 이 마이그레이션을 테스트했습니다. OpenAPI 3.0.3, 13개 태그에 걸친 62개 오퍼레이션이며, 시작하기, 인증, 통합 콘텐츠가 스펙의 description 필드에 작성되어 있었습니다. 임포트 시 어떤 일이 일어났는지는 다음과 같습니다. | 항목 | Apidog Spec-first Mode에서의 결과 | | --- | --- | | 오퍼레이션, 경로, 파라미터 | 그대로 임포트됨 (62개 중 62개) | | 스키마 및 components | 그대로 임포트됨 | | 보안 스킴 (API 키, 베어러, OAuth2) | 그대로 임포트됨 | | 태그 | 엔드포인트 폴더가 됨 (13개 중 13개) | | Git 동기화 | 저장소에 푸시하면 웹훅이 프로젝트를 업데이트 | | info.description | 임포트되지만 별도의 가이드 페이지로 렌더링되지는 않음 | | tags[].description | 임포트되지만 기본적으로 카테고리 소개 페이지로 표시되지는 않음 | | 저장소의 Markdown 파일 | 동기화되어 문서 페이지로 게시됨 | API 레퍼런스는 수정 없이 그대로 넘어옵니다. 빠지는 것은 서술형 콘텐츠입니다. description 필드가 같은 방식으로 렌더링되지 않는 이유 Redocly의 레퍼런스 문서를 구동하는 렌더러인 Redoc은 info.description을 하나의 미니 문서로 취급합니다. 그 안의 모든 Markdown 제목이 사이드바 항목이 되므로, 팀들은 흔히 "시작하기"와 "인증" 가이드 전체를 그곳에 작성합니다. 태그 설명은 각 태그 그룹 상단에 소개 텍스트로 렌더링됩니다. 이것은 Redoc의 관례일 뿐 OpenAPI 명세의 일부가 아닙니다. 명세는 description을 CommonMark 문자열로 정의할 뿐입니다. 대부분의 포털과 마찬가지로 Apidog는 가이드를 독립적인 Markdown 문서로 유지하고, 레퍼런스를 위해 스펙을 유지합니다. 임포트 후 기본 게시는 description 필드에 작성한 가이드 없이 API 레퍼런스만 보여줍니다. 해결책은 일회성 이동입니다. 그 콘텐츠를 YAML에서 꺼내 옆에 있는 Markdown 파일로 옮기는 것입니다. 그 이후로는 모든 것이 Git 기반으로 유지됩니다. 목표 저장소 레이아웃 우리가 검증한 구조는 다음과 같습니다. your-repo/ ├── openapi.yaml # API 레퍼런스의 소스 오브 트루스 └── docs/ ├── getting-started.md ├── authentication.md └── embed-integration-guide.md !Recommended repository layout for a Git-driven Apidog developer portal: openapi.yaml at the root, guides in docs/ openapi.yaml이 API 레퍼런스를 구동합니다. docs/의 각 파일은 포털 사이드바의 페이지가 됩니다. 해당 Markdown 파일이 참조하는 이미지는 같은 저장소에 두고 함께 동기화할 수 있습니다. Redocly의 sidebars.yaml로 내비게이션 순서를 지정했다면 참고용으로 보관하세요. Apidog의 문서 사이트 설정에서 같은 순서를 한 번만 지정하면 됩니다. 단계별 마이그레이션 1. description 필드 안에 무엇이 있는지 점검하세요 무엇이든 옮기기 전에 스펙에 얼마나 많은 콘텐츠가 들어 있는지 확인하세요. yq를 사용하면 다음과 같습니다. # How long is the top-level description? yq '.info.description' openapi.yaml | wc -w # Which headings does it contain? Each one is a Redoc sidebar entry today. yq '.info.description' openapi.yaml | grep -E '^#{1,3} ' # Which tags carry a description? yq '.tags[] | select(.description != null) | .name' openapi.yaml 제목 목록이 앞으로 만들 docs/ 파일 목록이 됩니다. 우리 테스트에서는 info.description이 두 개의 Markdown 파일로 나뉘었고, 태그 설명은 폴더별 소개 페이지와 추가 Markdown 파일 하나가 되었습니다. 2. info.description을 Markdown 파일로 분할하세요 각 최상위 섹션을 docs/ 아래의 개별 파일로 복사하세요. 제목, 코드 샘플, 링크는 유지합니다. 그런 다음 스펙의 info.description을 한 문단 요약으로 줄여서 콘텐츠가 한 곳에만 존재하도록 하세요. 복사할 때 Redoc 특유의 기능 두 가지에 주의하세요. - <SecurityDefinitions /> 및 이와 유사한 Redoc 태그는 Redoc 외부에서는 렌더링되지 않습니다. 이를 레퍼런스의 보안 스킴으로 연결되는 짧은 서술 섹션으로 교체하세요. - #tag/Payments 같은 링크는 Redoc 앵커를 가리킵니다. 첫 게시 후 해당하는 Apidog 문서나 폴더 URL로 업데이트하세요. 3. Spec-first Mode에서 저장소를 연결하세요 Spec-first Mode에서 프로젝트를 만들고, 저장소(GitHub, GitLab, Azure DevOps 또는 Bitbucket)를 연결하고, openapi.yaml과 docs/ 폴더를 지정한 뒤 웹훅을 설치하세요. 그 이후로는 추적 중인 브랜치에 푸시하면 프로젝트가 업데이트됩니다. !Creating a Spec-first Mode project in Apidog: connect a GitHub repository, pick the main branch and tick Install Webhook 첫 동기화 후 Specs 워크스페이스에 스펙과 저장소의 나머지가 표시됩니다. APIs 탭에는 openapi.yaml에서 파싱된 오퍼레이션이 나열되고, Docs에는 Markdown 페이지가 담기며, All files는 저장소를 그대로 반영합니다. !The Specs workspace in Apidog after a Git sync, with APIs, Docs and All files tabs and a Synced just now status 이것을 docs-as-code 워크플로로 유지해 주는 것이 바로 웹훅입니다. 웹훅이 없으면 동기화를 수동으로 트리거해야 합니다. 이것이 왜 중요한지 다시 알고 싶다면 docs as code 가이드를 참고하세요. 4. 문서 사이트를 게시하고 내비게이션을 설정하세요 프로젝트에서 문서 사이트를 게시하고 사이드바를 구성하세요. 대부분의 Redocly 사용자가 원하는 순서이자 우리가 재현한 순서는 다음과 같습니다. 1. 시작하기 2. 인증 3. 통합 가이드 4. API 레퍼런스 (태그에서 생성된 엔드포인트 폴더) Markdown 페이지와 API 폴더는 하나의 트리에서 자유롭게 섞이므로 현재 Redocly 사이드바와 거의 동일하게 맞출 수 있습니다. 5. 사용자 지정 도메인을 추가하세요 developers.example.com 같은 CNAME을 문서 사이트로 지정하세요. 사용자 지정 도메인은 Free 플랜에서도 사용할 수 있습니다. Apidog CLI로 코딩 에이전트가 태그 설명을 마이그레이션하게 하세요 태그 설명이 가장 지루한 부분입니다. 태그가 13개면 복사-붙여넣기 작업이 13번이고, 전환 중에 태그 설명이 바뀔 때마다 다시 해야 합니다. 대신 코딩 에이전트에게 맡기세요. Apidog CLI는 Claude Code, Codex, Cursor 또는 모든 터미널 에이전트에 엔드포인트 폴더를 포함한 프로젝트 리소스에 대한 구조화된 JSON 접근을 제공합니다. 한 번만 설정하세요. npm install -g apidog-cli@latest apidog auth login --with-token <YOUR_ACCESS_TOKEN> npx -y skills add https://apidog.com 마지막 줄은 Apidog 스킬을 설치하여 에이전트가 명령을 추측하지 않고 알 수 있게 합니다. 설치 가이드에서 토큰과 프라이빗 배포를 다룹니다. 그런 다음 에이전트에게 프롬프트 하나를 주세요. > openapi.yaml을 읽어라. 설명이 있는 모든 태그에 대해 Apidog 프로젝트 <PROJECT_ID>에서 일치하는 엔드포인트 폴더를 찾아 그 폴더의 설명을 태그의 설명으로 설정하라. 쓰기 전에 각 페이로드를 apidog cli-schema validate folder-update로 검증하라. 변경한 폴더 목록을 보여달라. 에이전트가 실행하는 내용은 다음과 같습니다. # Find the folder IDs that correspond to your tags apidog folder list --project <PROJECT_ID> --type endpoint # Check the payload shape instead of guessing it apidog cli-schema get folder-update # For each tag: write {"description": "..."} to a file, validate, then update apidog cli-schema validate folder-update --file ./payments-folder.json apidog folder update <FOLDER_ID> --project <PROJECT_ID> --type endpoint \ --file ./payments-folder.json !apidog cli-schema get folder-update shows the folder description field the agent writes to folder-update 스키마는 name, parentId, description을 허용하며, description은 엔드포인트 폴더와 테스트 시나리오 폴더에서 지원됩니다. 단일 태그에 속하지 않는 가이드의 경우, 에이전트는 apidog doc list와 apidog doc create를 같은 방식으로 사용할 수 있으며, 이때 apidog cli-schema get doc-create를 먼저 읽습니다. 게시된 사이트에서 폴더의 소개를 표시하려면 폴더 설정의 Documentation Settings after Publication에서 Folder Contents Displaying Setting을 설정하세요. !Apidog folder settings: Documentation Settings after Publication, with Directory Tree Display Style and Folder Contents Displaying Setting 솔직한 단서 하나: 태그 설명을 카테고리별 소개 페이지로 노출하는 것은 작동하지만, 문서화가 덜 된 경로에 의존합니다. 모든 폴더에서 이것에 의존하기 전에 자신의 워크스페이스에서 두세 개 폴더로 테스트해 보세요. 더 많은 에이전트 기반 스펙 작업은 Claude Code에서 Apidog CLI 사용하기와 에이전트가 API 스펙을 업데이트하게 하기를 참고하세요. Git 밖에 남는 것 Spec-first 프로젝트는 API와 Markdown을 Git에 유지합니다. 몇 가지 포털 설정은 Apidog 인터페이스에 있으며 버전 관리되지 않습니다. | 설정 | 위치 | | --- | --- | | openapi.yaml (엔드포인트, 스키마, 보안) | Git | | docs/의 가이드 페이지 | Git | | 문서 사이트 게시 | Apidog 인터페이스 | | 사이드바 순서 및 내비게이션 | Apidog 인터페이스 | | 폴더 소개 표시 설정 | Apidog 인터페이스 | | 사용자 지정 도메인 | Apidog 인터페이스 및 DNS | 이것들은 한 번만 설정하는 항목입니다. 새 최상위 섹션을 추가할 때 건드리는 것이지, 콘텐츠를 변경할 때마다 건드리는 것이 아닙니다. Redocly는 이 중 더 많은 것을 redocly.yaml과 sidebars.yaml에 보관하므로, 오늘날 풀 리퀘스트에서 내비게이션 변경을 검토한다면 그것이 UI로 이동할 것이라는 점을 계획에 넣으세요. 플랜 및 가격 여기서 설명한 설정은 사용자 지정 도메인을 포함해 Free 플랜에 맞습니다. Free는 최대 4명의 팀원까지 지원합니다. 유료 플랜은 프로젝트당 여러 문서 사이트, 사용자 지정 공개 범위 제어 같은 것을 추가합니다. 현재 한도는 Apidog 가격을 확인하세요. 마이그레이션 후 Redocly vs. Apidog | | Redocly | Apidog Spec-first Mode | | --- | --- | --- | | Git에 있는 스펙 | 예 | 예 | | Git에 Markdown으로 있는 가이드 | 예 | 예 | | 푸시 시 자동 동기화 | 예 | 예, 웹훅을 통해 | | info.description 안의 가이드 | 사이드바 섹션으로 렌더링됨 | Markdown 파일로 이동 | | 내비게이션 설정 | Git의 sidebars.yaml | Apidog 인터페이스 | | API 테스트, 모킹, 디버깅 | 별도 도구 | 같은 프로젝트 | | CLI를 통한 에이전트 접근 | Redocly CLI (lint, bundle, build) | Apidog CLI (프로젝트 리소스 읽기 및 쓰기) | 트레이드오프는 단순합니다. YAML로 정의된 내비게이션을 잃습니다. 대신 문서가 나오는 같은 스펙 위에서 테스트, 모킹, 에이전트 친화적 CLI를 얻습니다. CLI 대 CLI 비교는 Apidog CLI vs Redocly CLI를 읽어보세요. FAQ Redocly에서 호스팅하던 URL이 계속 작동하나요? 자동으로는 아닙니다. 페이지 경로가 바뀝니다. 기존 포털에 트래픽이 많은 가이드 URL이 있었다면, 도메인을 전환한 후 주요 페이지에 대해 DNS나 프록시 계층에서 리디렉션을 추가하세요. OpenAPI 스펙을 다시 작성해야 하나요? 아닙니다. 스펙은 그대로 임포트됩니다. 서술형 콘텐츠를 info.description과 tags[].description에서 Markdown 파일로 옮기기만 하면 됩니다. x-tagGroups를 유지할 수 있나요? 대신 폴더로 그룹화하세요. 각 태그가 폴더가 되고, 폴더를 중첩하여 태그 그룹을 재현할 수 있습니다. Stoplight에서 마이그레이션하는 것과 비교하면 어떤가요? 형태는 비슷합니다. 스펙은 Git에, Markdown은 옆에, 웹훅 동기화. 두 도구를 모두 운영한다면 Stoplight에서 Apidog로 마이그레이션하는 방법을 참고하세요. 내 워크스페이스에서 단계가 다르게 동작하면 어떻게 하나요? 우리 결과는 테스트 환경에서 나온 것입니다. DNS를 전환하기 전에 먼저 브랜치에서 임포트를 다시 실행하고 게시된 포털을 현재 포털과 비교하세요. 오후 한나절에 이동을 끝내세요 Redocly에서 Apidog로의 마이그레이션은 대부분 콘텐츠 이동입니다. 스펙은 그대로 임포트됩니다. 가이드는 description 필드에서 docs/ 폴더로 한 번만 옮깁니다. 그 후에는 웹훅이 모든 것을 동기화 상태로 유지합니다. 반복적인 태그 설명 작업은 Apidog CLI로 에이전트가 처리하게 하고, 자신의 시간은 게시된 포털을 페이지별로 확인하는 데 쓰세요. Apidog 다운로드하고 저장소를 Spec-first Mode에 연결하여 마이그레이션을 시작하세요. {% embed youtube.com %}

Como migrar do Redocly para o Apidog sem perder seu fluxo de trabalho Docs-as-Code Como migrar do Redocly para o Apidog sem perder seu fluxo de trabalho Docs-as-Code Se você executa seu portal do desenvolvedor no Redocly, você já trabalha da maneira que a maioria das equipes de API deseja: openapi.yaml fica no Git, os guias são Markdown, e um push atualiza a documentação. O medo ao trocar de ferramenta é perder esse ciclo e acabar editando a documentação manualmente em uma interface web. {% cta apidog.com %} Experimente o Apidog hoje {% endcta %} Você não precisa. O Apidog Spec-first Mode mantém sua especificação e seu Markdown no mesmo repositório, sincroniza a cada push por meio de um webhook e publica um portal com guias e uma referência de API em uma única barra lateral. Este guia percorre a migração, incluindo a única parte que não é transferida automaticamente: o conteúdo de formato longo que muitos usuários do Redocly mantêm dentro de info.description e tags[].description. Se você ainda está comparando ferramentas, comece com Apidog vs. Redocly ou a lista mais ampla de alternativas ao Redocly. Este post pressupõe que você escolheu o Apidog e deseja migrar sem quebrar seu fluxo de trabalho. O que é transferido e o que não é Testamos esta migração com uma especificação de produção real: OpenAPI 3.0.3, 62 operações em 13 tags, com conteúdo de introdução, autenticação e integração escrito nos campos de descrição da especificação. Veja o que aconteceu na importação. | Item | Resultado no Apidog Spec-first Mode | | --- | --- | | Operações, caminhos, parâmetros | Importado intacto (62 de 62) | | Esquemas e components | Importado intacto | | Esquemas de segurança (chave de API, bearer, OAuth2) | Importado intacto | | Tags | Tornaram-se pastas de endpoint (13 de 13) | | Sincronização Git | Push para o repositório, webhook atualiza o projeto | | info.description | Importado, mas não renderizado como páginas de guia separadas | | tags[].description | Importado, mas não exibido como páginas de introdução de categoria por padrão | | Arquivos Markdown no repositório | Sincronizados e publicados como páginas de documentação | A referência da API é transferida sem edições. A lacuna é o conteúdo narrativo. Por que seus campos de descrição não são renderizados da mesma forma Redoc, o renderizador por trás dos documentos de referência do Redocly, trata info.description como um mini-documento. Cada cabeçalho Markdown dentro dele se torna uma entrada na barra lateral, então as equipes frequentemente escrevem seus guias completos de “Primeiros passos” e “Autenticação” lá. As descrições de tags são renderizadas como texto de introdução no topo de cada grupo de tags. Essa é uma convenção do Redoc, não faz parte da Especificação OpenAPI. A especificação define apenas description como uma string CommonMark. O Apidog, como a maioria dos portais, mantém os guias como documentos Markdown independentes e mantém a especificação para a referência. Uma publicação padrão após a importação mostra apenas a referência da API, sem os guias que você escreveu nos campos de descrição. A correção é uma movimentação única: retire esse conteúdo do YAML e coloque-o em arquivos Markdown ao lado dele. Depois disso, tudo permanece orientado pelo Git. A estrutura do repositório de destino Esta é a estrutura que validamos: your-repo/ ├── openapi.yaml # source of truth for the API reference └── docs/ ├── getting-started.md ├── authentication.md └── embed-integration-guide.md !Recommended repository layout for a Git-driven Apidog developer portal: openapi.yaml at the root, guides in docs/ openapi.yaml orienta a referência da API. Cada arquivo em docs/ se torna uma página na barra lateral do portal. As imagens referenciadas por esses arquivos Markdown podem ficar no mesmo repositório e sincronizar com eles. Se você usou o sidebars.yaml do Redocly para ordenar sua navegação, mantenha-o como referência. Você definirá a mesma ordem uma vez nas configurações do site de documentação do Apidog. Migração passo a passo 1. Audite o que está dentro dos seus campos de descrição Antes de mover qualquer coisa, veja quanto conteúdo está na especificação. Com yq: # How long is the top-level description? yq '.info.description' openapi.yaml | wc -w # Which headings does it contain? Each one is a Redoc sidebar entry today. yq '.info.description' openapi.yaml | grep -E '^#{1,3} ' # Which tags carry a description? yq '.tags[] | select(.description != null) | .name' openapi.yaml A lista de cabeçalhos é sua futura lista de arquivos em docs/. Em nosso teste, info.description se dividiu em dois arquivos Markdown, e as descrições de tags se tornaram páginas de introdução por pasta, mais um arquivo Markdown extra. 2. Divida info.description em arquivos Markdown Copie cada seção de nível superior para seu próprio arquivo em docs/. Mantenha os cabeçalhos, exemplos de código e links. Em seguida, reduza info.description na especificação para um resumo de um parágrafo, para que o conteúdo fique em apenas um lugar. Fique atento a dois recursos específicos do Redoc enquanto copia: - <SecurityDefinitions /> e tags Redoc similares não são renderizadas fora do Redoc. Substitua-as por uma pequena seção escrita que vincule aos esquemas de segurança na referência. - Links como #tag/Payments apontam para âncoras do Redoc. Atualize-os para os URLs correspondentes de documentos ou pastas do Apidog após a primeira publicação. 3. Conecte o repositório no Spec-first Mode Crie um projeto no Spec-first Mode, conecte seu repositório (GitHub, GitLab, Azure DevOps ou Bitbucket), aponte-o para openapi.yaml e a pasta docs/, e instale o webhook. A partir de então, um push para o branch rastreado atualiza o projeto. !Creating a Spec-first Mode project in Apidog: connect a GitHub repository, pick the main branch and tick Install Webhook Após a primeira sincronização, o workspace Specs mostra sua especificação e o restante do repositório. A aba APIs lista as operações analisadas de openapi.yaml, Docs contém suas páginas Markdown, e All files espelha o repositório. !The Specs workspace in Apidog after a Git sync, with APIs, Docs and All files tabs and a Synced just now status O webhook é o que mantém isso como um fluxo de trabalho de docs-as-code. Sem ele, você teria que acionar sincronizações manualmente. Para relembrar por que isso importa, veja nosso guia sobre documentação como código. 4. Publique o site de documentação e defina a navegação Publique um site de documentação a partir do projeto e organize a barra lateral. A ordem que a maioria dos usuários do Redocly deseja, e a que reproduzimos, é: 1. Primeiros Passos 2. Autenticação 3. Guias de integração 4. Referência da API (as pastas de endpoint das suas tags) Páginas Markdown e pastas de API se misturam livremente em uma árvore, então você pode corresponder de perto à sua barra lateral atual do Redocly. 5. Adicione seu domínio personalizado Aponte um CNAME como developers.example.com para o site de documentação. Domínios personalizados estão disponíveis no plano Gratuito. Deixe seu agente de codificação migrar descrições de tags com o Apidog CLI As descrições de tags são a parte mais tediosa. Treze tags significam treze trabalhos de copiar e colar, e você os refará toda vez que uma descrição de tag mudar durante a transição. Entregue isso ao seu agente de codificação em vez disso. Apidog CLI fornece ao Claude Code, Codex, Cursor ou qualquer agente de terminal acesso JSON estruturado ao seu projeto, incluindo pastas de endpoint. Configure-o uma vez: npm install -g apidog-cli@latest apidog auth login --with-token <YOUR_ACCESS_TOKEN> npx -y skills add https://apidog.com A última linha instala a skill do Apidog para que seu agente conheça os comandos sem adivinhar. O guia de instalação cobre tokens e implantações privadas. Em seguida, dê ao seu agente um [REDACTED PROMPT] no projeto Apidog <PROJECT_ID> e defina a descrição dessa pasta como a descrição da tag. Valide cada payload com apidog cli-schema validate folder-update antes de escrever. Mostre-me a lista de pastas que você alterou. Veja o que o agente executa: # Find the folder IDs that correspond to your tags apidog folder list --project <PROJECT_ID> --type endpoint # Check the payload shape instead of guessing it apidog cli-schema get folder-update # For each tag: write {"description": "..."} to a file, validate, then update apidog cli-schema validate folder-update --file ./payments-folder.json apidog folder update <FOLDER_ID> --project <PROJECT_ID> --type endpoint \ --file ./payments-folder.json !apidog cli-schema get folder-update shows the folder description field the agent writes to O esquema folder-update aceita name, parentId e description, e description é suportado em pastas de endpoint e de cenário de teste. Para guias que não pertencem a uma única tag, o agente pode usar apidog doc list e apidog doc create da mesma forma, após ler apidog cli-schema get doc-create. Para mostrar a introdução de uma pasta no site publicado, defina Folder Contents Displaying Setting nas configurações da pasta em Documentation Settings after Publication. !Apidog folder settings: Documentation Settings after Publication, with Directory Tree Display Style and Folder Contents Displaying Setting Um aviso honesto: exibir descrições de tags como páginas de introdução por categoria funciona, mas depende de um caminho menos documentado. Teste em duas ou três pastas em seu próprio workspace antes de depender disso para todas elas. Para mais trabalho de especificação orientado por agente, veja usando Apidog CLI no Claude Code e deixando um agente atualizar sua especificação de API. O que fica fora do Git Um projeto Spec-first mantém sua API e seu Markdown no Git. Algumas configurações do portal ficam na interface do Apidog e não são controladas por versão: | Configuração | Onde fica | | --- | --- | | openapi.yaml (endpoints, esquemas, segurança) | Git | | Páginas de guia em docs/ | Git | | Publicação do site de documentação | Interface do Apidog | | Ordem da barra lateral e navegação | Interface do Apidog | | Configurações de exibição de introdução de pasta | Interface do Apidog | | Domínio personalizado | Interface do Apidog e seu DNS | Esses são itens configurados uma vez. Você mexe neles quando adiciona uma nova seção de nível superior, não a cada alteração de conteúdo. O Redocly mantém mais disso em redocly.yaml e sidebars.yaml, então se você revisa alterações de navegação em pull requests hoje, planeje isso para se mover para a UI. Plano e preços A configuração descrita aqui se encaixa no plano Gratuito, com domínio personalizado incluído. O Gratuito cobre até 4 membros da equipe. Planos pagos adicionam coisas como vários sites de documentação por projeto e controles de visibilidade personalizados. Confira preços do Apidog para os limites atuais. Redocly vs. Apidog após a migração | | Redocly | Apidog Spec-first Mode | | --- | --- | --- | | Especificação no Git | Sim | Sim | | Guias como Markdown no Git | Sim | Sim | | Sincronização automática no push | Sim | Sim, via webhook | | Guias dentro de info.description | Renderizados como seções da barra lateral | Mover para arquivos Markdown | | Configuração de navegação | sidebars.yaml no Git | Interface do Apidog | | Teste, mocking, depuração de API | Ferramentas separadas | Mesmo projeto | | Acesso do agente via CLI | Redocly CLI (lint, bundle, build) | Apidog CLI (ler e escrever recursos do projeto) | A troca é simples. Você perde a navegação definida em YAML. Você ganha testes, mocking e uma CLI amigável para agentes na mesma especificação de onde sua documentação vem. Para uma análise CLI por CLI, leia Apidog CLI vs Redocly CLI. Perguntas frequentes Meus URLs hospedados no Redocly continuarão funcionando? Não automaticamente. Os caminhos das páginas mudam. Se seu portal antigo tinha URLs de guias com alto tráfego, adicione redirecionamentos na sua camada de DNS ou proxy para as páginas principais após trocar o domínio. Preciso reescrever minha especificação OpenAPI? Não. A especificação é importada como está. Você apenas move o conteúdo narrativo de info.description e tags[].description para arquivos Markdown. Posso manter x-tagGroups? Use pastas para agrupamento em vez disso. Cada tag se torna uma pasta, e você pode aninhar pastas para reproduzir seus grupos de tags. Como isso se compara a migrar do Stoplight? A forma é semelhante: especificação no Git, Markdown ao lado, sincronização por webhook. Veja como migrar do Stoplight para o Apidog se você usa ambas as ferramentas. E se um passo se comportar de maneira diferente no meu workspace? Nossos resultados vieram de um ambiente de teste. Execute novamente a importação em um branch primeiro e compare o portal publicado com o atual antes de trocar o DNS. Faça a mudança em uma tarde Uma migração do Redocly para o Apidog é principalmente uma movimentação de conteúdo. Sua especificação é importada como está. Seus guias saem dos campos de descrição para uma pasta docs/ uma vez. Um webhook mantém tudo sincronizado depois disso. Deixe seu agente lidar com o trabalho repetitivo de descrição de tags com o Apidog CLI, e gaste seu próprio tempo verificando o portal publicado página por página. Baixe o Apidog e conecte seu repositório ao Spec-first Mode para iniciar a migração. {% embed youtube.com %}

Cách chuyển từ Redocly sang Apidog mà không mất quy trình Docs-as-Code Cách chuyển từ Redocly sang Apidog mà không mất quy trình Docs-as-Code Nếu bạn đang chạy cổng thông tin dành cho nhà phát triển (developer portal) trên Redocly, bạn vốn đã làm việc theo cách mà hầu hết các đội ngũ API mong muốn: openapi.yaml nằm trong Git, các hướng dẫn viết bằng Markdown, và chỉ cần push là tài liệu được cập nhật. Nỗi lo khi đổi công cụ là đánh mất vòng lặp đó và rốt cuộc phải chỉnh sửa tài liệu bằng tay trên giao diện web. {% cta apidog.com %} Dùng thử Apidog ngay hôm nay {% endcta %} Bạn không cần phải như vậy. Chế độ Spec-first Mode của Apidog giữ nguyên spec và các file Markdown của bạn trong cùng một repository, đồng bộ mỗi lần push thông qua webhook, và xuất bản một cổng thông tin với các hướng dẫn cùng phần tham chiếu API trong cùng một thanh điều hướng bên. Bài viết này sẽ hướng dẫn từng bước quá trình chuyển đổi, bao gồm cả phần không thể tự động chuyển sang: nội dung dài mà nhiều người dùng Redocly thường để trong info.description và tags[].description. Nếu bạn vẫn đang cân nhắc giữa các công cụ, hãy bắt đầu với Apidog vs. Redocly hoặc danh sách rộng hơn về các lựa chọn thay thế Redocly. Bài viết này giả định rằng bạn đã chọn Apidog và muốn chuyển đổi mà không làm gián đoạn quy trình làm việc của mình. Những gì giữ nguyên và những gì không Chúng tôi đã thử nghiệm quá trình chuyển đổi này với một spec thực tế đang chạy production: OpenAPI 3.0.3, 62 thao tác (operation) trải khắp 13 tag, với nội dung bắt đầu, xác thực và tích hợp được viết thẳng vào các trường description của spec. Đây là những gì đã xảy ra khi import. | Hạng mục | Kết quả trong Apidog Spec-first Mode | | --- | --- | | Operations, paths, parameters | Import nguyên vẹn (62/62) | | Schemas và components | Import nguyên vẹn | | Security schemes (API key, bearer, OAuth2) | Import nguyên vẹn | | Tags | Trở thành các thư mục endpoint (13/13) | | Đồng bộ Git | Push lên repo, webhook cập nhật project | | info.description | Được import, nhưng không hiển thị thành các trang hướng dẫn riêng | | tags[].description | Được import, nhưng mặc định không hiển thị thành các trang giới thiệu theo danh mục | | Các file Markdown trong repo | Được đồng bộ và xuất bản thành các trang tài liệu | Phần tham chiếu API chuyển sang mà không cần chỉnh sửa gì. Khoảng trống nằm ở nội dung dạng tường thuật. Vì sao các trường description của bạn không hiển thị giống nhau Redoc, trình render đứng sau phần tài liệu tham chiếu của Redocly, coi info.description như một tài liệu thu nhỏ. Mọi tiêu đề Markdown bên trong nó đều trở thành một mục trong thanh điều hướng bên, vì vậy các đội ngũ thường viết toàn bộ hướng dẫn "Bắt đầu" và "Xác thực" ở đó. Phần mô tả của tag được render thành văn bản giới thiệu ở đầu mỗi nhóm tag. Đó là một quy ước của Redoc, không phải một phần của Đặc tả OpenAPI. Đặc tả chỉ định nghĩa description là một chuỗi CommonMark. Apidog, giống như hầu hết các cổng thông tin khác, giữ các hướng dẫn dưới dạng tài liệu Markdown độc lập và giữ spec cho phần tham chiếu. Một lần xuất bản mặc định sau khi import sẽ chỉ hiển thị phần tham chiếu API, mà không có các hướng dẫn bạn đã viết trong các trường description. Cách khắc phục là một thao tác di chuyển chỉ làm một lần: tách nội dung đó ra khỏi YAML và đưa vào các file Markdown nằm cạnh nó. Sau đó, mọi thứ vẫn vận hành theo hướng Git. Bố cục repository đích Đây là cấu trúc mà chúng tôi đã kiểm chứng: your-repo/ ├── openapi.yaml # source of truth for the API reference └── docs/ ├── getting-started.md ├── authentication.md └── embed-integration-guide.md !Recommended repository layout for a Git-driven Apidog developer portal: openapi.yaml at the root, guides in docs/ openapi.yaml điều khiển phần tham chiếu API. Mỗi file trong docs/ trở thành một trang trong thanh điều hướng của cổng thông tin. Các hình ảnh được tham chiếu bởi những file Markdown đó có thể nằm cùng trong repo và được đồng bộ cùng chúng. Nếu bạn đã dùng sidebars.yaml của Redocly để sắp xếp thứ tự điều hướng, hãy giữ nó lại làm tham chiếu. Bạn sẽ thiết lập đúng thứ tự đó một lần trong phần cài đặt docs site của Apidog. Chuyển đổi từng bước 1. Kiểm tra nội dung bên trong các trường description của bạn Trước khi di chuyển bất cứ thứ gì, hãy xem có bao nhiêu nội dung nằm trong spec. Với yq: # How long is the top-level description? yq '.info.description' openapi.yaml | wc -w # Which headings does it contain? Each one is a Redoc sidebar entry today. yq '.info.description' openapi.yaml | grep -E '^#{1,3} ' # Which tags carry a description? yq '.tags[] | select(.description != null) | .name' openapi.yaml Danh sách tiêu đề chính là danh sách file docs/ tương lai của bạn. Trong thử nghiệm của chúng tôi, info.description được tách thành hai file Markdown, và các mô tả tag trở thành các trang giới thiệu cho từng thư mục cộng thêm một file Markdown nữa. 2. Tách info.description thành các file Markdown Sao chép từng phần cấp cao nhất vào file riêng của nó trong docs/. Giữ nguyên tiêu đề, mẫu code và liên kết. Sau đó thu gọn info.description trong spec thành một đoạn tóm tắt duy nhất, để nội dung chỉ tồn tại ở một nơi. Hãy chú ý hai tính năng đặc thù của Redoc khi sao chép: - Các thẻ Redoc như <SecurityDefinitions /> và tương tự sẽ không render bên ngoài Redoc. Hãy thay chúng bằng một đoạn viết ngắn liên kết tới các security scheme trong phần tham chiếu. - Các liên kết như #tag/Payments trỏ tới các neo (anchor) của Redoc. Hãy cập nhật chúng thành URL trang tài liệu hoặc thư mục tương ứng trong Apidog sau lần xuất bản đầu tiên. 3. Kết nối repository trong Spec-first Mode Tạo một project trong Spec-first Mode, kết nối repository của bạn (GitHub, GitLab, Azure DevOps hoặc Bitbucket), trỏ nó tới openapi.yaml và thư mục docs/, rồi cài đặt webhook. Từ đó trở đi, mỗi lần push lên nhánh được theo dõi sẽ cập nhật project. !Creating a Spec-first Mode project in Apidog: connect a GitHub repository, pick the main branch and tick Install Webhook Sau lần đồng bộ đầu tiên, workspace Specs sẽ hiển thị spec của bạn và phần còn lại của repository. Tab APIs liệt kê các operation được phân tích từ openapi.yaml, Docs chứa các trang Markdown của bạn, và All files phản chiếu toàn bộ repo. !The Specs workspace in Apidog after a Git sync, with APIs, Docs and All files tabs and a Synced just now status Webhook chính là thứ giữ cho quy trình này vận hành theo kiểu docs-as-code. Không có nó, bạn sẽ phải kích hoạt đồng bộ bằng tay. Để nhắc lại vì sao điều này quan trọng, hãy xem hướng dẫn của chúng tôi về docs as code. 4. Xuất bản docs site và thiết lập điều hướng Xuất bản một docs site từ project và sắp xếp thanh điều hướng bên. Thứ tự mà hầu hết người dùng Redocly muốn, và cũng là thứ tự chúng tôi đã tái tạo, là: 1. Bắt đầu (Getting Started) 2. Xác thực (Authentication) 3. Các hướng dẫn tích hợp 4. Tham chiếu API (các thư mục endpoint từ tag của bạn) Các trang Markdown và thư mục API kết hợp tự do trong cùng một cây, nên bạn có thể dựng gần giống thanh điều hướng Redocly hiện tại của mình. 5. Thêm tên miền tùy chỉnh của bạn Trỏ một bản ghi CNAME như developers.example.com tới docs site. Tên miền tùy chỉnh có sẵn ở gói Free. Để coding agent của bạn chuyển các mô tả tag bằng Apidog CLI Mô tả tag là phần tẻ nhạt nhất. Mười ba tag nghĩa là mười ba lần copy-paste, và bạn sẽ phải làm lại mỗi khi một mô tả tag thay đổi trong quá trình chuyển đổi. Hãy giao việc đó cho coding agent của bạn. Apidog CLI cho phép Claude Code, Codex, Cursor hoặc bất kỳ agent chạy trên terminal nào truy cập có cấu trúc dưới dạng JSON vào project của bạn, bao gồm cả các thư mục endpoint. Hãy thiết lập một lần: npm install -g apidog-cli@latest apidog auth login --with-token <YOUR_ACCESS_TOKEN> npx -y skills add https://apidog.com Dòng cuối cùng cài đặt skill Apidog để agent của bạn biết các lệnh mà không phải đoán. Hướng dẫn cài đặt đề cập đến token và các triển khai riêng tư (private deployment). Sau đó, đưa cho agent của bạn một câu lệnh: > Đọc openapi.yaml. Với mỗi tag có mô tả, hãy tìm thư mục endpoint tương ứng trong project Apidog <PROJECT_ID> và đặt mô tả của thư mục đó bằng mô tả của tag. Kiểm tra (validate) từng payload bằng apidog cli-schema validate folder-update trước khi ghi. Cho tôi xem danh sách các thư mục bạn đã thay đổi. Đây là những gì agent sẽ chạy: # Find the folder IDs that correspond to your tags apidog folder list --project <PROJECT_ID> --type endpoint # Check the payload shape instead of guessing it apidog cli-schema get folder-update # For each tag: write {"description": "..."} to a file, validate, then update apidog cli-schema validate folder-update --file ./payments-folder.json apidog folder update <FOLDER_ID> --project <PROJECT_ID> --type endpoint \ --file ./payments-folder.json !apidog cli-schema get folder-update shows the folder description field the agent writes to Schema folder-update chấp nhận name, parentId và description, và description được hỗ trợ trên các thư mục endpoint và test-scenario. Với những hướng dẫn không thuộc về một tag duy nhất, agent có thể dùng apidog doc list và apidog doc create theo cách tương tự, sau khi đọc apidog cli-schema get doc-create. Để hiển thị phần giới thiệu của một thư mục trên site đã xuất bản, hãy đặt Folder Contents Displaying Setting trong phần cài đặt của thư mục đó, mục Documentation Settings after Publication. !Apidog folder settings: Documentation Settings after Publication, with Directory Tree Display Style and Folder Contents Displaying Setting Một lưu ý thẳng thắn: việc hiển thị mô tả tag thành các trang giới thiệu theo từng danh mục là làm được, nhưng nó dựa vào một lối đi ít được ghi chép rõ ràng. Hãy thử trên hai hoặc ba thư mục trong workspace của riêng bạn trước khi phụ thuộc vào nó cho tất cả. Để biết thêm về các công việc liên quan đến spec do agent thực hiện, hãy xem dùng Apidog CLI trong Claude Code và để agent cập nhật spec API của bạn. Những gì nằm ngoài Git Một project Spec-first giữ API và các file Markdown của bạn trong Git. Một vài cài đặt của cổng thông tin nằm trong giao diện Apidog và không được quản lý phiên bản: | Cài đặt | Nơi lưu trữ | | --- | --- | | openapi.yaml (endpoints, schemas, security) | Git | | Các trang hướng dẫn trong docs/ | Git | | Xuất bản docs site | Giao diện Apidog | | Thứ tự thanh điều hướng và điều hướng | Giao diện Apidog | | Cài đặt hiển thị phần giới thiệu thư mục | Giao diện Apidog | | Tên miền tùy chỉnh | Giao diện Apidog và DNS của bạn | Đây là những mục chỉ cần thiết lập một lần. Bạn chỉ động tới chúng khi thêm một mục cấp cao nhất mới, chứ không phải mỗi lần thay đổi nội dung. Redocly giữ nhiều thứ trong số này trong redocly.yaml và sidebars.yaml, nên nếu hiện nay bạn xem xét các thay đổi điều hướng qua pull request, hãy chuẩn bị tinh thần rằng việc đó sẽ chuyển sang giao diện UI. Gói dịch vụ và giá Thiết lập được mô tả ở đây phù hợp với gói Free, bao gồm cả tên miền tùy chỉnh. Gói Free hỗ trợ tối đa 4 thành viên nhóm. Các gói trả phí bổ sung những thứ như nhiều docs site trên mỗi project và các kiểm soát hiển thị tùy chỉnh. Hãy xem bảng giá Apidog để biết các giới hạn hiện tại. Redocly vs. Apidog sau khi chuyển đổi | | Redocly | Apidog Spec-first Mode | | --- | --- | --- | | Spec trong Git | Có | Có | | Hướng dẫn dạng Markdown trong Git | Có | Có | | Tự động đồng bộ khi push | Có | Có, qua webhook | | Hướng dẫn nằm trong info.description | Được render thành các mục trong thanh điều hướng | Chuyển sang các file Markdown | | Cấu hình điều hướng | sidebars.yaml trong Git | Giao diện Apidog | | Kiểm thử API, mock, gỡ lỗi | Công cụ riêng biệt | Cùng một project | | Truy cập cho agent qua CLI | Redocly CLI (lint, bundle, build) | Apidog CLI (đọc và ghi tài nguyên project) | Sự đánh đổi rất đơn giản. Bạn mất phần điều hướng được định nghĩa bằng YAML. Bạn nhận được khả năng kiểm thử, mock và một CLI thân thiện với agent trên chính spec mà tài liệu của bạn lấy làm nguồn. Để xem so sánh từng lệnh CLI một, hãy đọc Apidog CLI vs Redocly CLI. Câu hỏi thường gặp Các URL được host trên Redocly của tôi có tiếp tục hoạt động không? Không tự động. Đường dẫn trang sẽ thay đổi. Nếu cổng thông tin cũ của bạn có những URL hướng dẫn có lượng truy cập cao, hãy thêm chuyển hướng (redirect) ở tầng DNS hoặc proxy cho các trang chính sau khi bạn đổi tên miền. Tôi có phải viết lại spec OpenAPI của mình không? Không. Spec được import nguyên trạng. Bạn chỉ cần chuyển nội dung dạng tường thuật ra khỏi info.description và tags[].description vào các file Markdown. Tôi có thể giữ x-tagGroups không? Hãy dùng thư mục để nhóm thay vào đó. Mỗi tag trở thành một thư mục, và bạn có thể lồng các thư mục vào nhau để tái tạo các nhóm tag của mình. Điều này so với việc chuyển từ Stoplight thì thế nào? Hình thức tương tự: spec trong Git, Markdown nằm cạnh nó, đồng bộ bằng webhook. Hãy xem cách chuyển từ Stoplight sang Apidog nếu bạn dùng cả hai công cụ. Nếu một bước nào đó hoạt động khác trong workspace của tôi thì sao? Kết quả của chúng tôi đến từ một môi trường thử nghiệm. Hãy chạy lại quá trình import trên một nhánh trước và so sánh cổng thông tin đã xuất bản với cổng hiện tại của bạn trước khi đổi DNS. Hoàn tất việc chuyển đổi trong một buổi chiều Chuyển từ Redocly sang Apidog chủ yếu là một thao tác di chuyển nội dung. Spec của bạn được import nguyên trạng. Các hướng dẫn của bạn được chuyển ra khỏi các trường description vào thư mục docs/ một lần. Sau đó, một webhook giữ mọi thứ đồng bộ. Hãy để agent của bạn xử lý công việc lặp đi lặp lại là mô tả tag bằng Apidog CLI, và dành thời gian của chính bạn để kiểm tra cổng thông tin đã xuất bản từng trang một. Tải Apidog và kết nối repo của bạn với Spec-first Mode để bắt đầu quá trình chuyển đổi. {% embed youtube.com %}

🧩 Need just one value from a giant YAML file? yq queries and edits YAML, JSON and other formats from the terminal. Useful in scripts and config work. 🔧 mikefarah/yq #YAML #CLI #浇朋友 #蓝朋友 #互关 #fo

A pure PHP 8.5 alternative to jq and yq More of an exercise but perhaps with some utility..? jq and yq are both excellent command line utilities that allow you to query json and yaml files respectively with something akin to xpath and also feature other capabilities. Highly recommened you check them out if you didn't know about them. I often find myself including them in scripted utilities and processes, however you do have to make sure they are installed and the correct version. I wondered how hard it would be to create PHP equivalent? Performance wise it's pretty good - PHP's own startup time bumps up the startup benchmarks, but really this isn't about trying to outdo them on performance as much as allow a PHP project, CI etc to declare another composer dependency and then have the jq and yq style functionality available It's totally new and unproven, but I will be actively dog fooding it It has got me wondering what we can do to really open up high performance CLI utilities in PHP. What is the SOTA on this kind of thing - standalone binaries that could bundle maybe a stripped down PHP and have other optimstaions done to allow fast PHP based CLI tools? >!AI - the code/repo was 100% AI written with human coordination, this post is organic meat fingers on keyboard!<