การแปลงข้อมูลจำเพาะของ Swagger JSON เป็นเอกสาร HTML

Question 1

สำหรับ REST API บางตัวที่เขียนด้วย PHP ฉันถูกขอให้สร้างเอกสารSwaggerและเนื่องจากฉันไม่รู้วิธีง่ายๆในการเพิ่มคำอธิบายประกอบให้กับ API ที่มีอยู่เหล่านั้นและสร้างเอกสารดังกล่าวฉันจึงใช้ตัวแก้ไขนี้เพื่อสร้างบางส่วนในตอนนี้

ฉันบันทึกไฟล์ JSON และ YAML ที่สร้างโดยใช้โปรแกรมแก้ไขนั้นและตอนนี้ฉันต้องสร้างเอกสาร Swagger แบบโต้ตอบขั้นสุดท้าย (คำสั่งนี้อาจฟังดูไร้เดียงสาและคลุมเครือ)

ใครช่วยบอกฉันหน่อยได้ไหมว่าฉันจะแปลงไฟล์ข้อมูลจำเพาะ Swagger JSON เป็นเอกสาร Swagger จริงได้อย่างไร

ฉันอยู่บนแพลตฟอร์ม Windows และไม่รู้อะไรเกี่ยวกับ Ant / Maven

Question 2

ฉันไม่พอใจกับswagger-codegenตอนที่ฉันกำลังมองหาเครื่องมือในการทำสิ่งนี้ดังนั้นฉันจึงเขียนของฉันเอง ลองดูbootprint-swagger

เป้าหมายหลักเมื่อเทียบกับswagger-codegenคือการตั้งค่าที่ง่าย (แม้ว่าคุณจะต้องใช้ nodejs) และควรปรับเปลี่ยนสไตล์และเทมเพลตให้เข้ากับความต้องการของคุณได้ง่ายซึ่งเป็นฟังก์ชันหลักของbootprint -project

Question 3

พยายามที่จะใช้redoc-CLI

ผมใช้bootprint-openapiโดยที่ฉันได้รับการสร้างพวงของไฟล์ ( bundle.js, bundle.js.map, index.html, main.cssและmain.css.map) และจากนั้นคุณสามารถแปลงมันเป็นหนึ่ง.htmlไฟล์โดยใช้HTML-อินไลน์เพื่อสร้างง่ายindex.htmlไฟล์

จากนั้นฉันพบว่าredoc-cliใช้งานง่ายมากและผลลัพธ์ก็น่ากลัวจริงๆไฟล์index.html เดียวและสวยงาม

การติดตั้ง :

npm install -g redoc-cli

การใช้งาน :

redoc-cli bundle -o index.html swagger.json

Question 4

ทุกอย่างยากเกินไปหรือมีเอกสารไม่ดีดังนั้นฉันจึงแก้ไขสิ่งนี้ด้วยสคริปต์ง่ายๆswagger-yaml-to-html.pyซึ่งใช้งานได้เช่นนี้

python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html

สิ่งนี้มีไว้สำหรับ YAML แต่การแก้ไขให้ทำงานกับ JSON ก็เป็นเรื่องเล็กน้อยเช่นกัน

Question 5

ลองดูสวย ๆ

มันมี

มีลักษณะคล้ายกับแผงด้านขวาของSwagger-Editor
ค้นหา / กรอง
Schema Folding
คำติชมสด
เอาต์พุตเป็นไฟล์ html เดียว

ฉันกำลังดู Swagger Editor และคิดว่ามันสามารถส่งออกบานหน้าต่างแสดงตัวอย่างได้ แต่กลับกลายเป็นว่าทำไม่ได้ เลยเขียนเวอร์ชั่นของตัวเอง

การเปิดเผยข้อมูลทั้งหมด: ฉันเป็นผู้เขียนเครื่องมือ

Question 6

ดูโครงการswagger-api / swagger-codegenบน GitHub; โครงการ README แสดงวิธีใช้เพื่อสร้าง HTML แบบคงที่ ดูการสร้างเอกสาร API แบบ HTML แบบคงที่

หากคุณต้องการดู swagger.json คุณสามารถติดตั้ง Swagger UIและเรียกใช้งานได้ คุณเพียงแค่ปรับใช้บนเว็บเซิร์ฟเวอร์ (โฟลเดอร์ dist หลังจากที่คุณโคลน repo จาก GitHub) และดู Swagger UI ในเบราว์เซอร์ของคุณ มันเป็นแอพ JavaScript

Question 7

ฉันใช้เวลานานมากและลองใช้วิธีแก้ปัญหาต่างๆมากมายในที่สุดฉันก็ทำแบบนี้:

<html>
    <head>    
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3.17.0/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>

คุณต้องมีpath / to / my / swagger.yamlจากตำแหน่งเดียวกัน
(หรือใช้ส่วนหัว CORS)

Question 8

คุณยังสามารถดาวน์โหลด ui ผยองได้จาก: https://github.com/swagger-api/swagger-uiใช้โฟลเดอร์ dist แก้ไข index.html: เปลี่ยนตัวสร้าง

const ui = SwaggerUIBundle({
    url: ...,

เป็น

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

ตอนนี้โฟลเดอร์ dist มีทุกสิ่งที่คุณต้องการและสามารถแจกจ่ายได้ตามที่เป็นอยู่

Question 9

ดูลิงค์นี้: http://zircote.com/swagger-php/installation.html

ดาวน์โหลดไฟล์ phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
ติดตั้ง Composer https://getcomposer.org/download/
ทำให้ composer.json
โคลน swagger-php / ไลบรารี
โคลน swagger-ui / library
สร้างคลาสทรัพยากรและโมเดล php สำหรับ API
เรียกใช้ไฟล์ PHP เพื่อสร้าง json
ให้เส้นทางของ json ใน api-doc.json
กำหนดเส้นทางของ api-doc.json ใน index.php ภายในโฟลเดอร์ swagger-ui dist

หากคุณต้องการความช่วยเหลืออื่นโปรดอย่าลังเลที่จะถาม

Question 10

มีโปรแกรม Javaขนาดเล็กที่สร้างเอกสาร (adoc หรือ md) จากไฟล์ yaml

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withSwaggerMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withOutputLanguage(Language.DE)
        .build();

Swagger2MarkupConverter builder = Swagger2MarkupConverter.from(yamlFileAsString).withConfig(config).build();
return builder.toFileWithoutExtension(outFile);

แต่น่าเสียดายที่จะสนับสนุนเฉพาะOpenAPI 2.0แต่ไม่OpenAPI 3.0

Question 11

สำหรับ Swagger API 3.0 การสร้างรหัสไคลเอนต์ Html2 จาก Swagger Editor ออนไลน์ทำงานได้ดีสำหรับฉัน!