Widget pour de la documentation type API

IGNF / cartes.gouv.fr-documentation

Site de documentation statique pour le cartes.gouv.fr

https://ignf.github.io/cartes.gouv.fr-documentation/

MIT License

2 stars 5 forks source link

Widget pour de la documentation type API #2

Closed slafayIGN closed 5 months ago

slafayIGN commented 10 months ago

Documenter des appels à des API de façon à décrire les requêtes et les réponses.

Ces éléments peuvent concerner une seule requête, insérée dans une documentation plus large de type article.

Exemple de rendu :

Ce rendu est basé sur les admonition collapsible de material https://squidfunk.github.io/mkdocs-material/reference/admonitions/ Avec un peu de personnalisation pour les verbes API, leur donner une apparence swagger-ui-like.

slafayIGN commented 8 months ago

On ajoute ou complète des composants du DSFR pour réaliser cet élément :

[x] le composant Alerte
[x] le composant Accordéon
[ ] le composant Onglet (reste à faire)

L'utilisation combinée de ces 3 composants permet un démarrage propre sur cet élément.

slafayIGN commented 5 months ago

L'url à copier dans l'en-tête du composant accordéon (comme dans le titre du composant admonition) pose problème pour être copier.

Une nouvelle suggestion consiste à :

afficher l'url dans un bloc de code
afficher le reste des détails (éventuels corps de requête et de réponse) dans un accordéon)

Ainsi les URL avec ou sans détails ont la même allure et sont copiables et les contenus code des détails ne prennent pas beaucoup de place dans la page. Le fonctionnement en 2 onglets (quand il y a requête ET réponse) est abandonné.

marionLX commented 5 months ago

top! c'est bien compatible accessibilité?