Introduzione allo Sviluppo con Axe DevTools Linter

Questo articolo descrive come iniziare a utilizzare i servizi API REST forniti dall'edizione on-premises di Axe DevTools Linter o da Axe DevTools Linter SaaS. I servizi sono forniti da endpoint REST, quindi è necessaria esperienza con uno strumento REST come Postman, CocoaRestClient o l'estensione VS Code REST Client. È possibile accedere ai servizi anche con un linguaggio di programmazione come Python.

Le differenze tra le due edizioni di Axe DevTools Linter (Axe DevTools Linter SaaS vs. il server on-premises) sono che l'offerta SaaS richiede l'autorizzazione tramite API ad ogni richiesta al linter (l'endpoint /lint-source).

Primi Passi

Se si utilizza l'edizione SaaS di Axe DevTools Linter Server, è necessario prima ottenere una chiave API. Puoi trovare i passaggi necessari per ottenere la chiave in Ottenere una Chiave API di Axe DevTools Linter SaaS.

Per la versione on-premises del Server Axe DevTools Linter, sarà necessario configurarlo (come dettagliato in Installazione del Server Axe DevTools Linter On-Premises) e poi ottenere l'indirizzo IP del server. Sarà inoltre necessario il numero di porta su cui il server è in ascolto (il default è la porta 3000).

Testare la Connessione con curl

Due degli endpoint REST di Axe DevTools Linter SaaS non richiedono autenticazione, quindi puoi testare la tua connessione prima di ottenere una chiave API.

Se vuoi eseguire un semplice test per verificare l'accesso al server, puoi usare curl (o un browser web). Il seguente esempio di curl mostra come usare l'endpoint status di Axe DevTools Linter SaaS:

curl https://axe-linter.deque.com/status

Per la versione on-premises, digiteresti quanto segue:

curl http://<server IP address>:<server port>/status

Devi sostituire <indirizzo IP del server> e <porta del server> nel comando sopra.

Se il server è disponibile, risponderà con:

Ok

Puoi anche visitare lo stesso URL (per esempio, https://axe-linter.deque.com/status) con un browser web e dovresti vedere lo stesso risultato.

Il seguente esempio mostra come accedere all'endpoint healthcheck:

curl https://axe-linter.deque.com/healthcheck

Il server dovrebbe rispondere con quanto segue:

{
  "version": "4.4.0"
}

Come per l'endpoint status, puoi anche visitare https://axe-linter.deque.com/healthcheck con un browser web e ottenere lo stesso risultato come con curl.

Per controllare il codice sorgente per errori di accessibilità, è necessario creare una richiesta POST. Puoi usare curl o uno strumento come Postman.

In Postman o in un altro strumento REST, è necessario creare un'intestazione come quella mostrata di seguito:

POST https://axe-linter.deque.com/lint-source
content-type: application/json
authorization: <YOUR API KEY>

Se stai utilizzando Axe DevTools Linter SaaS, devi sostituire con la tua chiave API. Se stai utilizzando il server on-premises, non devi usare l'intestazione authorization, ma devi cambiare l'URL con l'indirizzo IP e la porta del tuo server on-premises.

Con curl l'intestazione equivalente a quella mostrata sopra sarebbe:

curl --request POST --url https://axe-linter.deque.com/lint-source \
  --header 'content-type: application/json' \
  --header 'authorization: <YOUR API KEY>'

È inoltre necessario specificare un corpo della richiesta come oggetto JSON prima che la richiesta sia completa:

{
  "source": "# Heading\n### Another Heading\n",
  "filename": "file.md"
}

Il comando curl completo è:

curl --request POST --url https://axe-linter.deque.com/lint-source \
  --header 'content-type: application/json' \
  --header 'authorization: <YOUR API KEY>'
  --data '{ "source": "# Heading\n### Another Heading\n",
    "filename": "file.md" }'

Per il server on-premises, è necessario modificare l'argomento --url e rimuovere la riga --header 'authorization: <LA TUA CHIAVE API>'.

Di seguito viene mostrato un esempio di risposta alla richiesta sopra:

HTTP/1.1 200 OK
Date: Mon, 14 Mar 2022 14:04:19 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 419
Connection: close
X-Powered-By: Express
Surrogate-Control: no-store
Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
Pragma: no-cache
Expires: 0
ETag: W/"1a3-cfgZ30xjvW815mLDpbjoGXreu2o"

{
  "report": {
    "errors": [
      {
        "ruleId": "heading-order",
        "helpURL": "https://dequeuniversity.com/rules/axe/4.4/heading-order?application=axe-linter",
        "description": "Ensures the order of headings is semantically correct",
        "lineContent": "### Another heading",
        "lineNumber": 2,
        "linterType": "md",
        "column": 1,
        "endColumn": 20
      }
    ]
  }
}

Poiché questo esempio presenta un problema di accessibilità, hai ricevuto una risposta che contiene un oggetto report contenente un array errori di oggetti errore. Vedi Risposta per maggiori informazioni su questo oggetto di risposta.

Se la tua chiave API non esiste quando utilizzi Axe DevTools Linter SaaS, riceverai una risposta come questa:

HTTP/1.1 404 Not Found
Date: Fri, 11 Mar 2022 22:38:51 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 33
Connection: close
X-Powered-By: Express
Surrogate-Control: no-store
Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
Pragma: no-cache
Expires: 0
ETag: W/"21-HAVNeHb+a8RfOcMl419aKM67S20"

{
  "error": "No API key found"
}

In questo caso, puoi provare a ricreare la tua chiave API o contattare l'Help Desk di Deque per assistenza.

Vedi anche

• Consulta Ottenere una chiave API per i passaggi necessari per ottenere una chiave API necessaria per utilizzare Axe DevTools Linter SaaS.
• Consulta Riferimento API REST del Server Axe DevTools Linter per un riferimento alle API fornite da Axe DevTools Linter Server e ulteriori opzioni per l'endpoint linter-source.
• Il Esempio di utilizzo dell'API REST di Axe DevTools Linter contiene un esempio curl e un esempio Python che puoi utilizzare con Axe DevTools Linter Server.