Forum Programmation.autre Webservice : Outils pour générer de la doc

Posté par  . Licence CC By‑SA.
Étiquettes : aucune
-1
30
mai
2013

Bonjour,

Je suis à la recherche d'outils de doc orienté API de webservice.

Idéalement je voudrais que
- les templates ne soit pas trop compliqué à personnaliser,
- qu'il soit facile d'ajouter des exemples concret sans polluer la source
- quick link intelligent

Cette histoire me dépites un peu et j'ai besoin d'un peu d'air frais de votre part sur le sujet.

a+

  • # MarkDown

    Posté par  (site Web personnel) . Évalué à 0.

    Salut

    Je viens de finir un doc d'API pour un webservice ^

    Alors l'idée :

    La documentation est écrite dans fichier au format MarkDown : MaDoc.md

    Ensuite dans un répertoire sur un serveur web, tu crées un fichier madoc.php qui contient :

            <!DOCTYPE html>
            <html>
            <title>Doc API</title>
            <meta charset='utf-8'>
            <xmp theme="united" style="display:none;">
            <?php include('MaDoc.md'); ?>
            </xmp>
    
            <script src="http://strapdownjs.com/v/0.2/strapdown.js"></script>
            </html>
    
    

    Et avec ton navigateur tu as une belle doc mise en page :)

    Tu as un éditeur online markdown ici : http://markable.in/editor/

    • [^] # Re: MarkDown

      Posté par  . Évalué à 0.

      Hello,

      ta solution est aussi élégante que simple. Et plutôt agréable à l'oeil.

      Comparée à des solutions telles que http://apiary.io/ ou https://developers.helloreverb.com/swagger/ elle me semble cependant trop simpliste.

      Par contre je lui reconnaît d'avoir l'intelligence d'être portable, ce que apiary n'est pas et que swagger parvient difficilement à réaliser du fait des ces dépendances (java / scala / maven) (sauf bien sur pour un développeur java, mais ce n'est pas mon terrain, donc voilà quoi).

      Du coup comme ça me dépite toujours, eh oui… J'ai démarré un nouveau projet, pour tirer partit des idées des deux projets suscités, mais avec les avantages de ce plier à mes désirs. On verra ce que ça donne !

Suivre le flux des commentaires

Note : les commentaires appartiennent à ceux qui les ont postés. Nous n’en sommes pas responsables.