La documentazione API inizia spesso in Word una specifica di progetto, descrizioni di endpoint o una guida di riferimento legacy. Migratare tale contenuto in una moderna piattaforma di documentazione significa convertirlo in Markdown (o in un formato derivato da esso). Questa guida descrive il miglior approccio per Word a API documentazione conversione.
Perché spostare API Documenti a Markdown
Le moderne piattaforme di documentazione API sono costruite attorno a Markdown e/o OpenAPI:
- GitHub / GitLab Markdown README e pagine wiki
- - Non è vero. Documenti basati su Markdown con integrazione di riferimento API
- GitBook Markdown file con navigazione strutturata
- Riduci Markdown descrizioni incorporate nelle specifiche di OpenAPI
- Fabbricazione di lastre Documenti basati su Ruby da file Markdown
Iniziando con pulito Markdown da WordToMD significa che puoi prendere di mira qualsiasi di queste piattaforme.
Convertire API documentazione da Word
- Aprire la specifica o il progetto di documentazione Word API
- Trascinare il file .docx su WordToMD
- Revisione dell'output prestare particolare attenzione alle tabelle (spesso utilizzate per gli elenchi dei parametri) e ai blocchi di codice
- Scaricare o copiare il Markdown
Strutturazione API Riferimento Markdown
La documentazione API ha una struttura standard. Dopo la conversione, organizzare in questo modello:
# API Reference
## Authentication
All requests require an API key in the `Authorization` header.
```http
Authorization: Bearer YOUR_API_KEYPunto finale
GET/utilizzatori
Restituisce un elenco di tutti gli utenti.
Parametri
| Nome | Tipo | Requisiti | Descrizione |
|---|---|---|---|
limit | integer | - No , no , no , no . | Risultati massimi (di default: 20) |
offset | integer | - No , no , no , no . | Ofset di paginazione |
Risposta
{
"users": [
{ "id": 1, "name": "Alice" }
],
"total": 42
}
## Parameter Tables
Word tables often contain parameter definitions. These convert cleanly to GFM tables:
```markdown
| Parameter | Type | Description |
|---|---|---|
| `api_key` | string | Your API key |
| `format` | string | Response format: `json` or `xml` |
| `limit` | integer | Number of results (max 100) |Per i dettagli sulla formattazione delle tabelle, vedere Markdown Tabelle: una guida completa.
Esempi di codice
La documentazione API si basa fortemente su campioni di codice. Dopo la conversione con WordToMD, blocchi di codici di formato con identificatori linguistici:
```bash
curl -X POST https://api.example.com/v1/users \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Alice", "email": "alice@example.com"}'
```
```python
import requests
response = requests.post(
"https://api.example.com/v1/users",
headers={"Authorization": "Bearer TOKEN"},
json={"name": "Alice", "email": "alice@example.com"}
)
```Vede la tabella Markdown Guida ai blocchi di codice per tutti gli identificatori linguistici supportati.
Integrazione con OpenAPI / Swagger
Le specifiche di OpenAPI utilizzano YAML o JSON, non Markdown ma le descrizioni Markdown sono incorporate all'interno della specifica:
paths:
/users:
get:
summary: List users
description: |
Returns a paginated list of all users.
Supports filtering by `status` and `role`.
parameters:
- name: limit
in: query
description: "Maximum number of results (default: 20, max: 100)"
schema:
type: integerIl description campo accetta Markdown. Copia il testo della descrizione pertinente dal tuo Markdown convertito e incollalo nella specifica OpenAPI YAML.
ReadMe.io Flusso di lavoro
ReadMe.io è una popolare piattaforma di documentazione API:
- Convertire i vostri documenti Word API con WordToMD
- In ReadMe, creare una nuova pagina guida
- Passare all'editor Markdown
- Incolla il convertito Markdown
- Link al tuo riferimento API (generato da OpenAPI) dalle pagine guida
ReadMe rende standard Markdown più qualche sintassi di callout personalizzata.
GitBook per API Documenti
Per un sito di riferimento API in GitBook, vedere Word a Markdown per GitBook. GitBook works well for documentation-heavy APIs where narrative guides are as important as the reference.
Rubriche nella documentazione API
API Documenti di riferimento richiedono una gerarchia di intestazione coerente per la navigazione:
#Titolo del documento/categoria##Risorsa o sezione (e.g., Authentication, User, Orders)###Endpoint individuale (e.g., GET /users, POST /orders)####Sottocomponenti (e.g., Organismo di richiesta, Risposta)
Applicare questa struttura dopo la conversione. Vede la tabella Markdown Guida delle rubriche.
Versione API Documentazione
Per i documenti API con versione:
- Utilizzare file separati per versione (
v1/,v2/(direttori) - Oppure utilizzare rami specifici di versione in Git
- Includere la versione in prima pagina o nella prima rubrica
# API Reference v2.1FAQ
Il mio Word doc ha esempi di richiesta/risposta HTTP come testo formattato. Si convertiranno correttamente?
Il testo preformattato (letteratura Courier/monospazio) viene convertito in codice in linea. I blocchi a più linee possono richiedere una recinzione manuale. Aggiungere ```http or ```json Cerchiamo di aggirarli dopo la conversione.
Posso generare la specifica OpenAPI da un documento Word? Non direttamente OpenAPI richiede una struttura YAML/JSON leggibile in macchina. Ma puoi usare il convertito Markdown come fonte per le descrizioni e assemblare o generare manualmente l'OpenAPI YAML.
Che dire delle funzioni interattive "Proviamo"? Piattaforme come ReadMe e Redocly aggiungono funzionalità Try It in cima alle specifiche di OpenAPI. Il contenuto Markdown è la parte narrativa; OpenAPI è la specifica leggibile dalla macchina. Entrambe le questioni sono separate.
C'è un modo per convalidare la mia documentazione API Markdown?
Usate un linter come markdownlint per problemi di sintassi, e la funzione di anteprima della piattaforma di documentazione per individuare i problemi di rendering.
Conclusioni
Conversione Word a Markdown per la documentazione API è il primo passo per modernizzare i vostri documenti API. WordToMD gestisce la conversione; la tua piattaforma di destinazione (ReadMe, GitBook, Redocly, o semplice GitHub) gestisce la pubblicazione. Concentrarsi su una gerarchia di intestazioni pulita e blocchi di codice ben formattati per il miglior risultato.