Voor sommige REST-API’s die in PHP zijn geschreven, werd mij gevraagd om Swagger-documentatie te maken, en aangezien ik niet op de hoogte was van eenvoudige manier om annotaties aan die bestaande API’s toe te voegen en zo’n documentatie te maken, heb ik deze editorgebruikt om er voorlopig een paar te genereren .
Ik heb de JSON- en YAML-bestanden opgeslagen die met die editor zijn gemaakt, en nu moet ik de definitieve interactieve Swagger-documentatie maken (deze verklaring klinkt misschien naïef en vaag).
Kan iemand me alsjeblieft laten weten hoe ik het Swagger JSON-specificatiebestand kan converteren naar daadwerkelijke Swagger-documentatie?
Ik ben op het Windows-platform en weet niets over Ant/Maven.
Antwoord 1, autoriteit 100%
Probeer redoc-clite gebruiken.
Ik gebruikte bootprint-openapiwaarmee ik een heleboel bestanden aan het genereren was (bundle.js, bundle.js.map, index.html, main.cssen main.css.map) en vervolgens kunt u het converteren naar een enkel .html-bestand met behulp van html-inlineom een eenvoudig index.html-bestand te genereren.
Toen vond ik redoc-cliheel gemakkelijk te gebruiken en de uitvoer is echt- 2 geweldig, een enkel en mooi index.htmlbestand.
Installatie:
npm install -g redoc-cli
Gebruik:
redoc-cli bundle -o index.html swagger.json
Antwoord 2, autoriteit 60%
Ik was niet tevreden met swagger-codegentoen ik op zoek was naar een tool om dit te doen, dus schreef ik mijn eigen tool. Kijk eens op bootprint-swagger
Het belangrijkste doel in vergelijking met swagger-codegenis om een eenvoudige installatie te bieden (hoewel je nodejs nodig hebt).
En het moet gemakkelijk zijn om styling en sjablonen aan uw eigen behoeften aan te passen, wat een kernfunctionaliteit is van het bootprint-project
Antwoord 3, autoriteit 31%
Alles was te moeilijk of slecht gedocumenteerd, dus ik heb dit opgelost met een eenvoudig script swagger-yaml-to-html .py, wat als volgt werkt
python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html
Dit is voor YAML, maar het is ook triviaal om het aan te passen zodat het met JSON werkt.
Antwoord 4, autoriteit 24%
Bekijk pretty-swag
Het heeft
- Vergelijkbaar met het rechterpaneel van Swagger-Editor
- Zoeken / filteren
- Schema vouwen
- Live feedback
- Uitvoer als een enkel html-bestand
Ik keek naar Swagger Editor en dacht dat het het voorbeeldvenster kon exporteren, maar dat bleek niet zo te zijn. Dus schreef ik er mijn eigen versie van.
Volledige openbaarmaking: ik ben de auteur van de tool.
Antwoord 5, autoriteit 24%
Ik heb veel tijd besteed en veel verschillende oplossingen geprobeerd – uiteindelijk deed ik het op deze manier:
<html>
<head>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui.css">
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<script>
function render() {
var ui = SwaggerUIBundle({
url: `path/to/my/swagger.yaml`,
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
]
});
}
</script>
</head>
<body onload="render()">
<div id="swagger-ui"></div>
</body>
</html>
U hoeft alleen pad / naar / my / swagger te hebben.yaml geserveerd vanaf dezelfde locatie.
(of gebruik CORS-headers)
6, Autoriteit 8%
Voor Swagger API 3.0, het genereren van HTML2-clientcode van online Swagger Editor werkt geweldig voor mij!
7
Als u uw JSON-bestand in Gitlab verbindt, wordt het voor u weergegeven.