Un site de documentation pour l'API
Générer automatiquement un site de documentation en utilisant:
- Un header et footer
- Les fichiers README.md de src/modules/
- La documentation récupérable depuis l'API lui-même par introspection
Comment?
Tech stack et déploiement
Avec un site svelte généré statiquement, hosté:
- en tant que gitlab page sur le repo inp-net/churros, ou
- avec un container, sur k8s, mais bon à voir si c'est utile de dockeriser et kubéiser un tas de .html
et publié sur
churros.inpt.fr/developers/docs
- Mettre un lien sur le playground GraphiQL (https://churros.inpt.fr/graphql)
Header et footer
+layout.svelte
;)
Pages
La page principale liste les différents modules ainsi que les pages de doc qui ne parlent pas de GraphQL. Il faut aussi des pages pour:
- Comment s'auth (dont un lien à la partie OAuth)
- L'existance des libs Python et NPM
- Les limitations globales (rate limiting, et ptet d'autres choses?)
Chaque module a sa page, récupéré avec un ptit
fs.walkDir
depackages/api/src/modules
. Pour chaque page, on inclut: - Le README.md du module (ptit
fs.readFile
) - Les types (objets et scalaires) (introspection GraphQL, et utilisation de
packages/api/src/modules/<module>/types/...
pour savoir lesquels mettre) - Les queries (pareil avec
resolvers/
) - Les mutations (pareil avec
resolvers/
) - Les subscrptions (you guessed it,
resolvers/
) L'inspi principale pour ça me vient de GraphDoc (c'est bo, exemple avec notre API Dans chaque page on peut linker à une query / type / subscription / mutation avec son nom (en kebab-case): -
/ticketing/queries/ticket
pour la queryticket
-
/posts/types/article
pour le typeArticle
-
/posts/mutations
pour les mutations du module "Posts"
Composants Svelte du site
Pour render de manière jolie tout ça, on crée des composants, genre:
-
Query.svelte
qui peut être de kindQuery
,Mutation
ouSubscription
-
Type.svelte
qui peut être de kindObject
,Scalar
ouEnum
Quid du reste qui n'est pas GraphQL?
On fait des +page.md
(avec mdsvex)