Перетворення специфікації Swagger JSON у документацію HTML

88

Для деяких REST API, написаних на PHP, мене попросили створити документацію Swagger , і оскільки я не знав жодного простого способу додавання анотацій до цих існуючих API та створення такої документації, я використовував цей редактор для того, щоб на даний момент створити деякі.

Я врятував файли JSON та YAML, створені за допомогою цього редактора, і тепер мені потрібно створити остаточну інтерактивну документацію Swagger (це твердження може звучати наївно і неясно).

Чи може хтось повідомити мене, як я можу перетворити файл специфікації Swagger JSON на фактичну документацію Swagger?

Я на платформі Windows і нічого не знаю про Ant / Maven.

yaml swagger swagger-php

— Саліл
джерело

я спробував [ github.com/wordnik/swagger-ui](Swagger UI), але це не відображає мій json. показано лише попередження: "Цей API використовує застарілу версію Swagger! Для отримання додаткової інформації див. github.com/wordnik/swagger-core/wiki ".

— Саліл

43

Мене не влаштовувало, swagger-codegenколи я шукав інструмент для цього, тому написав свій власний. Погляньте на bootprint-swagger

Основна мета порівняно з swagger-codegen- забезпечити просте налаштування (хоча вам знадобляться nodejs). І це повинно бути легко адаптувати дизайн і шаблони для власних потреб, що є основним функціоналом bootprint -project

— Нільс Кнаппмайер
джерело

9

Попередження: станом на 11/2016 автор bootprint-swagger, очевидно, відмовився від проекту. swagger-codegen все ще добре підтримується.

— Brent Matzelle

22

Я є автором, і в тексті сказано: "Мені шкода сказати, що я не зможу розробити нові функції для цього проекту найближчим часом. Але: я, мабуть, зможу обговорити та об'єднати запити на витяг, та опублікувати нові версії ". Ви можете назвати це занедбаним, я б назвав це "на утриманні". Я також запрошу всіх, хто зацікавлений внести свій внесок у проект.

— Нільс Кнаппмайер,

1

Знайдено, що spectacleгенерує набагато краще виглядаючу документацію з

— обманутого

Після багатої боротьби я знайшов цей інструмент дуже корисним: api-html

— Асфандіяр-хан

57

Спробуйте використовувати redoc-cli .

Я використовував bootprint-OpenAPI , з допомогою якого я генерує купу файлів ( bundle.js, bundle.js.map, index.html, main.cssі main.css.map) , а потім ви можете перетворити його в один .htmlфайл з допомогою HTML-інлайн для створення простого index.htmlфайлу.

Тоді я виявив, що redoc-cli дуже простий у використанні, і висновок справді-2 приголомшливий, єдиний і красивий файл index.html .

Встановлення :

npm install -g redoc-cli

Використання :

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

— Вікасдіп Сінгх
джерело

8

Цей інструмент дає дійсно найкрасивіші результати серед усіх згаданих інструментів.

— Якуб Моравец

1

Цей найкращий на сьогоднішній день imo, і оскільки ми створюємо його для розробників, які використовують настільні комп'ютери, розмір виводу не є проблемою.

— milosmns

3

Використання прямого виконуваного імені не завжди працює, виконання за допомогою програми npx redoc-cli ...є більш надійним.

— кошеня,

2

Дуже гарний вихід. Дякую за пропозицію.

— Сахіл Джейн

1

Це чудовий інструмент !! Дякую Вікас за чудову пропозицію, брате !! Безумовно, набагато кращий і менш незграбний, ніж bootstrap-openapi!

— Чатурведі Саураб

19

Ознайомтеся з гарною мовою

Це має

Подібно до вигляду правої панелі Swagger-Editor
Пошук / Фільтр
Складання схеми
Відгуки в режимі реального часу
Виведення у вигляді одного html-файлу

Я дивився на редактор Swagger і думав, що він може експортувати область попереднього перегляду, але виявилося, що не може. Тож я написав свою власну версію.

Повна інформація: Я автор інструменту.

— TLJ
джерело

1

Я виявив, що досить обмінна програма є простим та ідеальним інструментом з відповідними точками входу CLI та API. Моєю єдиною скаргою (і тією, яка змусила мене натомість розібратися зі складністю swagger-ui) була його невдала обробка композиції / розширення об’єкта. Будь-яке використання документа allOfв документі виробляє undefined, навіть у найпростіших сценаріях ("злиття" одного об'єкта, еквівалентне взагалі не використання allOf).

— ПочеснийMule

3

Щойно розгорнута allOfфункція для вас. Перевір.

— TLJ

2

Схоже, не підтримує Swagger / OpenAPI V3

— SeinopSys

18

Все було занадто складно або погано задокументовано, тому я вирішив це за допомогою простого скрипта swagger-yaml-to-html.py , який працює так

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

Це для YAML, але модифікувати його для роботи з JSON також тривіально.

— осейскар
джерело

Це чисте золото!

— zemirco

16

Дивіться проект swagger-api / swagger-codegen на GitHub; проект README показує, як використовувати його для створення статичного HTML. Див. Розділ Створення статичної документації html api .

Якщо ви хочете переглянути swagger.json, ви можете встановити інтерфейс Swagger та запустити його. Ви просто розгортаєте його на веб-сервері (папка dist після того, як ви клонуєте репо з GitHub) і переглядаєте інтерфейс Swagger у своєму браузері. Це додаток для JavaScript.

— djb
джерело

Дякую. Моя проблема полягала в тому, що користувальницький інтерфейс не приймав специфікації 2.0. Однак це виглядає як найпростіша відповідь, тому я прийму це (поки).

— Саліл

Інструменти Swagger все ще розвиваються до версії 2.0. Однак я виявив, що інтерфейс Swagger працює для моїх файлів 2.0, які починаються з "swagger": "2.0",

— djb

Крім того, з редактора Swagger ви можете експортувати специфікацію JSON (не як YAML, а як JSON), і інтерфейс Swagger повинен мати можливість читати це. (Примітка: swagger.json повинен знаходитись на тому самому хості / порту, що і додаток Swagger UI, або потрібно ввімкнути CORS; див. README.md у редакторі Swagger на GitHub

— djb

14

Я витратив багато часу і випробував безліч різних рішень - врешті-решт, я зробив це таким чином:

<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>

Вам просто потрібно, щоб шлях / до / мого / swagger.yaml обслуговувався з того самого місця.
(або використовуйте заголовки CORS)

— Кріс Рендалл
джерело

Чудово, дякую! Я використав <link rel = " styleheet " href = " petstore.swagger.io/swagger-ui.css "> <script src = " petstore.swagger.io/swagger-ui-bundle.js "></script >

— Ерандо,

1

Я виявив, що це найкраще рішення, не встановлюючи нічого!

— KurioZ7

Надзвичайно корисний. Ви заощадили багато часу.

— kalpesh khule

7

Ви також можете завантажити swagger ui з: https://github.com/swagger-api/swagger-ui , візьміть папку dist, змініть index.html: змініть конструктор

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

в

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

тепер папка dist містить усе необхідне і може бути розподілена як є

— користувач1928596
джерело

2

Погляньте на це посилання: 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 / бібліотеку
Створіть PHP-класи Resource та Model для API
Виконайте файл PHP для створення json
Дайте шлях до json в api-doc.json
Вкажіть шлях до api-doc.json у index.php всередині папки swagger-ui dist

Якщо вам потрібна інша допомога, будь ласка, запитайте.

— Сайед Раза Мехді
джерело

1

Чи є в Інтернеті редактор (крім редактора обману), який може генерувати це для мене? Я не хочу коментувати свої PHP API, якщо є простіший спосіб. Проблема, яку я зрозумів, полягає в тому, що редактор swagger генерує специфікацію swagger v2.0, і swagger-ui на сьогодні не справляється з цим.

— Саліл

@Salil Все, що я знаю, це те, що swagger надає власний он-лайн редактор, тобто editor.swagger.wordnik.com, я не знаю жодного іншого он-лайн редактора, якщо ви знайдете який-небудь ділитися ним з нами, дякую :)

— Syed Raza Мехді

2

Існує невелика програма 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 .

— Ерандо
джерело

2

Для Swagger API 3.0 генерація коду клієнта Html2 з онлайн-редактора Swagger для мене чудово працює!

— Кумар С
джерело

1

Я знайшов цей інструмент, який називається api-html, дуже корисним. Він генерує чудовий інтерфейс html5 з великою кількістю можливостей.

Є варіанти для генерації в Інтернеті або за допомогою інструмента cli .

Ось посилання на демо-версію, побудовану на "api-html": pets-demo

— Асфандіяр-хан
джерело