Konwersja specyfikacji Swaggera z formatu JSON do dokumentacji HTML

Question 1

W przypadku niektórych interfejsów API REST napisanych w PHP poproszono mnie o utworzenie dokumentacji Swagger , a ponieważ nie znałem łatwego sposobu dodawania adnotacji do tych istniejących interfejsów API i tworzenia takiej dokumentacji, użyłem tego edytora do wygenerowania na razie niektórych.

Zapisałem pliki JSON i YAML utworzone za pomocą tego edytora, a teraz muszę stworzyć ostateczną interaktywną dokumentację Swaggera (to stwierdzenie może brzmieć naiwnie i niejasno).

Czy ktoś może mi powiedzieć, jak mogę przekonwertować plik specyfikacji Swagger JSON na rzeczywistą dokumentację Swaggera?

Jestem na platformie Windows i nic nie wiem o Ant / Maven.

Question 2

Nie byłem zadowolony, swagger-codegengdy szukałem narzędzia do tego, więc napisałem własne. Spójrz na bootprint-swagger

Głównym celem w porównaniu do tego swagger-codegenjest zapewnienie łatwej konfiguracji (chociaż będziesz potrzebować nodejs). I powinno być łatwe dostosowanie stylizacji i szablonów do własnych potrzeb, co jest podstawową funkcjonalnością bootprint -projektu

Question 3

Spróbuj użyć redoc-cli .

Używałem bootprint-OpenAPI przez którą został wytwarzającą kilka plików ( bundle.js, bundle.js.map, index.html, main.cssi main.css.map), a następnie można przekształcić go w jednym .htmlpliku przy użyciu HTML-inline wygenerować prosty index.htmlplik.

Potem stwierdziłem, że redoc-cli jest bardzo łatwy w użyciu, a wynik jest naprawdę niesamowity, pojedynczy i piękny plik index.html .

Instalacja :

npm install -g redoc-cli

Użycie :

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

Question 4

Spójrz na ładny łup

To ma

Podobnie wygląda jak prawy panel edytora Swagger
Wyszukaj / Filtruj
Schemat składania
Informacje zwrotne na żywo
Dane wyjściowe jako pojedynczy plik HTML

Patrzyłem na Swagger Editor i myślałem, że może wyeksportować panel podglądu, ale okazało się, że nie może. Więc napisałem własną wersję tego.

Pełne ujawnienie: jestem autorem narzędzia.

Question 5

Wszystko było zbyt trudne lub źle udokumentowane, więc rozwiązałem to za pomocą prostego skryptu swagger-yaml-to-html.py , który działa w ten sposób

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

To jest dla YAML, ale modyfikacja go do pracy z JSON jest również trywialna.

Question 6

Zobacz projekt swagger-api / swagger-codegen na GitHub; projekt README pokazuje, jak używać go do generowania statycznego kodu HTML. Zobacz dokumentację Generowanie statycznego interfejsu API HTML .

Jeśli chcesz wyświetlić plik swagger.json, możesz zainstalować interfejs użytkownika interfejsu Swagger i uruchomić go. Wystarczy wdrożyć go na serwerze internetowym (folder dist po sklonowaniu repozytorium z GitHub) i wyświetlić interfejs użytkownika Swagger w przeglądarce. To aplikacja JavaScript.

Question 7

Spędziłem dużo czasu i wypróbowałem wiele różnych rozwiązań - w końcu zrobiłem to w ten sposób:

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

Wystarczy, że ścieżka / to / my / swagger.yaml będzie obsługiwana z tej samej lokalizacji.
(lub użyj nagłówków CORS)

Question 8

Możesz również pobrać Swagger UI z: https://github.com/swagger-api/swagger-ui , pobrać folder dist, zmodyfikować index.html: zmienić konstruktora

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

w

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

teraz folder dist zawiera wszystko, czego potrzebujesz i może być rozpowszechniany tak, jak jest

Question 9

Spójrz na ten link: http://zircote.com/swagger-php/installation.html

Pobierz plik phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
Zainstaluj Composer https://getcomposer.org/download/
Utwórz plik composer.json
Sklonuj plik swagger-php / library
Clone swagger-ui / library
Utwórz klasy php zasobów i modelu dla interfejsu API
Uruchom plik PHP, aby wygenerować plik json
Podaj ścieżkę do json w api-doc.json
Podaj ścieżkę do api-doc.json w index.php w folderze swagger-ui dist

Jeśli potrzebujesz dodatkowej pomocy, nie wahaj się zapytać.

Question 10

Jest mały program Java, który generuje dokumenty (adoc lub md) z pliku 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);

Niestety obsługuje tylko OpenAPI 2.0, ale nie obsługuje OpenAPI 3.0 .

Question 11

W przypadku Swagger API 3.0 generowanie kodu klienta Html2 z internetowego edytora Swagger działa świetnie!

Question 12

Zauważyłem, że to narzędzie o nazwie api-html jest bardzo przydatne. Generuje niesamowity interfejs użytkownika HTML5 z wieloma możliwościami.

Istnieją opcje generowania online lub za pośrednictwem narzędzia CLI .

Oto link do wersji demonstracyjnej opartej na „api-html”: Pets-demo

Answer 1

W przypadku niektórych interfejsów API REST napisanych w PHP poproszono mnie o utworzenie dokumentacji Swagger , a ponieważ nie znałem łatwego sposobu dodawania adnotacji do tych istniejących interfejsów API i tworzenia takiej dokumentacji, użyłem tego edytora do wygenerowania na razie niektórych.

Zapisałem pliki JSON i YAML utworzone za pomocą tego edytora, a teraz muszę stworzyć ostateczną interaktywną dokumentację Swaggera (to stwierdzenie może brzmieć naiwnie i niejasno).

Czy ktoś może mi powiedzieć, jak mogę przekonwertować plik specyfikacji Swagger JSON na rzeczywistą dokumentację Swaggera?

Jestem na platformie Windows i nic nie wiem o Ant / Maven.

Answer 2

Próbowałem [ github.com/wordnik/swagger-ui] ( Swagger UI), ale to nie renderuje mojego json. jedyne wyświetlane ostrzeżenie to „Ten interfejs API używa przestarzałej wersji Swaggera! Więcej informacji znajdziesz na github.com/wordnik/swagger-core/wiki ”.

Salil

Answer 3

43

Nie byłem zadowolony, swagger-codegengdy szukałem narzędzia do tego, więc napisałem własne. Spójrz na bootprint-swagger

Głównym celem w porównaniu do tego swagger-codegenjest zapewnienie łatwej konfiguracji (chociaż będziesz potrzebować nodejs). I powinno być łatwe dostosowanie stylizacji i szablonów do własnych potrzeb, co jest podstawową funkcjonalnością bootprint -projektu

Nils Knappmeier
źródło

9

Ostrzeżenie: Od 11/2016 autor bootprint-swagger najwyraźniej porzucił projekt. swagger-codegen jest nadal dobrze obsługiwany.

Brent Matzelle

22

Jestem autorem, a tekst mówi: „Przykro mi to mówić, że w najbliższej przyszłości nie będę w stanie opracować nowych funkcji dla tego projektu. Ale: Prawdopodobnie będę mógł omawiać i łączyć żądania ściągnięcia, i publikować nowe wersje. ” Możesz nazwać to porzuconym, ja bym to nazwał „zawieszonym”. Zaproszę również wszystkich, którzy są zainteresowani współtworzeniem projektu.

Nils Knappmeier

1

Okazało się, że spectaclegeneruje znacznie lepiej wyglądającą dokumentację z

Swagger

Po wielu zmaganiach uznałem to narzędzie za bardzo przydatne: api-html

Asfandiyar Khan

Answer 4

9

Ostrzeżenie: Od 11/2016 autor bootprint-swagger najwyraźniej porzucił projekt. swagger-codegen jest nadal dobrze obsługiwany.

Brent Matzelle

Answer 5

22

Jestem autorem, a tekst mówi: „Przykro mi to mówić, że w najbliższej przyszłości nie będę w stanie opracować nowych funkcji dla tego projektu. Ale: Prawdopodobnie będę mógł omawiać i łączyć żądania ściągnięcia, i publikować nowe wersje. ” Możesz nazwać to porzuconym, ja bym to nazwał „zawieszonym”. Zaproszę również wszystkich, którzy są zainteresowani współtworzeniem projektu.

Nils Knappmeier

Answer 6

1

Okazało się, że spectaclegeneruje znacznie lepiej wyglądającą dokumentację z

Swagger

Answer 7

Po wielu zmaganiach uznałem to narzędzie za bardzo przydatne: api-html

Asfandiyar Khan

Answer 8

57

Spróbuj użyć redoc-cli .

Używałem bootprint-OpenAPI przez którą został wytwarzającą kilka plików ( bundle.js, bundle.js.map, index.html, main.cssi main.css.map), a następnie można przekształcić go w jednym .htmlpliku przy użyciu HTML-inline wygenerować prosty index.htmlplik.

Potem stwierdziłem, że redoc-cli jest bardzo łatwy w użyciu, a wynik jest naprawdę niesamowity, pojedynczy i piękny plik index.html .

Instalacja :

npm install -g redoc-cli

Użycie :

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

Vikasdeep Singh
źródło

8

To narzędzie tworzy naprawdę najpiękniejszy wynik ze wszystkich wymienionych narzędzi.

Jakub Moravec,

1

Ten jest zdecydowanie najlepszy z imo, a ponieważ tworzymy go dla programistów, którzy używają komputerów stacjonarnych, rozmiar wyjściowy nie stanowi problemu.

milosmns

3

Używanie bezpośredniej nazwy pliku wykonywalnego nie zawsze działa, wykonanie przez npx redoc-cli ...jest bardziej niezawodne.

Przyczajony kotek

2

Bardzo piękny wydruk. Dzięki za sugestię.

Sahil Jain

1

To niesamowite narzędzie! Dzięki Vikas głęboko za cudowną sugestię brachu !! Zdecydowanie lepsze i mniej niezdarne niż bootstrap-openapi!

Chaturvedi Saurabh

Answer 9

8

To narzędzie tworzy naprawdę najpiękniejszy wynik ze wszystkich wymienionych narzędzi.

Jakub Moravec,

Answer 10

1

Ten jest zdecydowanie najlepszy z imo, a ponieważ tworzymy go dla programistów, którzy używają komputerów stacjonarnych, rozmiar wyjściowy nie stanowi problemu.

milosmns

Answer 11

3

Używanie bezpośredniej nazwy pliku wykonywalnego nie zawsze działa, wykonanie przez npx redoc-cli ...jest bardziej niezawodne.

Przyczajony kotek

Answer 12

2

Bardzo piękny wydruk. Dzięki za sugestię.

Sahil Jain

Answer 13

1

To niesamowite narzędzie! Dzięki Vikas głęboko za cudowną sugestię brachu !! Zdecydowanie lepsze i mniej niezdarne niż bootstrap-openapi!

Chaturvedi Saurabh

Answer 14

19

Spójrz na ładny łup

To ma

Podobnie wygląda jak prawy panel edytora Swagger
Wyszukaj / Filtruj
Schemat składania
Informacje zwrotne na żywo
Dane wyjściowe jako pojedynczy plik HTML

Patrzyłem na Swagger Editor i myślałem, że może wyeksportować panel podglądu, ale okazało się, że nie może. Więc napisałem własną wersję tego.

Pełne ujawnienie: jestem autorem narzędzia.

TLJ
źródło

1

Uważam, że pretty-swag jest prostym i idealnym narzędziem, z odpowiednimi punktami wejścia CLI i API. Moją jedyną skargą (i tą, która zmusiła mnie do zajęcia się złożonością interfejsu swagger-ui) było to, że nie radził sobie poprawnie z kompozycją / rozszerzaniem obiektów. Każde użycie allOfw dokumencie powoduje undefined, nawet w najprostszych scenariuszach („scalenie” pojedynczego obiektu, co jest równoznaczne z allOfcałkowitym nieużywaniem ).

HonoredMule

3

Właśnie allOfudostępniliśmy Ci funkcję. Sprawdź to.

TLJ

2

Wydaje się, że nie obsługuje Swagger / OpenAPI V3

SeinopSys

Answer 15

1

Uważam, że pretty-swag jest prostym i idealnym narzędziem, z odpowiednimi punktami wejścia CLI i API. Moją jedyną skargą (i tą, która zmusiła mnie do zajęcia się złożonością interfejsu swagger-ui) było to, że nie radził sobie poprawnie z kompozycją / rozszerzaniem obiektów. Każde użycie allOfw dokumencie powoduje undefined, nawet w najprostszych scenariuszach („scalenie” pojedynczego obiektu, co jest równoznaczne z allOfcałkowitym nieużywaniem ).

HonoredMule

Answer 16

3

Właśnie allOfudostępniliśmy Ci funkcję. Sprawdź to.

TLJ

Answer 17

2

Wydaje się, że nie obsługuje Swagger / OpenAPI V3

SeinopSys

Answer 18

18

Wszystko było zbyt trudne lub źle udokumentowane, więc rozwiązałem to za pomocą prostego skryptu swagger-yaml-to-html.py , który działa w ten sposób

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

To jest dla YAML, ale modyfikacja go do pracy z JSON jest również trywialna.

oseiskar
źródło

To jest czyste złoto!

zemirco

Answer 19

To jest czyste złoto!

zemirco

Answer 20

16

Zobacz projekt swagger-api / swagger-codegen na GitHub; projekt README pokazuje, jak używać go do generowania statycznego kodu HTML. Zobacz dokumentację Generowanie statycznego interfejsu API HTML .

Jeśli chcesz wyświetlić plik swagger.json, możesz zainstalować interfejs użytkownika interfejsu Swagger i uruchomić go. Wystarczy wdrożyć go na serwerze internetowym (folder dist po sklonowaniu repozytorium z GitHub) i wyświetlić interfejs użytkownika Swagger w przeglądarce. To aplikacja JavaScript.

djb
źródło

Dzięki. Mój problem polegał na tym, że swagger-ui nie akceptował specyfikacji 2.0. Jednak wygląda to na najprostszą odpowiedź, więc zaakceptuję to (na razie).

Salil

Narzędzia Swagger wciąż ewoluują w wersji 2.0. Jednak okazało się, że interfejs użytkownika Swaggera działa z moimi plikami 2.0, które zaczynają się od „swagger”: „2.0”,

djb

Ponadto z edytora Swagger możesz wyeksportować specyfikację JSON (nie jako YAML, ale jako JSON), a interfejs użytkownika Swagger powinien być w stanie to odczytać. (Uwaga: plik swagger.json musi znajdować się na tym samym hoście / porcie co aplikacja Swagger UI lub musisz włączyć CORS; zobacz

plik

Answer 21

Dzięki. Mój problem polegał na tym, że swagger-ui nie akceptował specyfikacji 2.0. Jednak wygląda to na najprostszą odpowiedź, więc zaakceptuję to (na razie).

Salil

Answer 22

Narzędzia Swagger wciąż ewoluują w wersji 2.0. Jednak okazało się, że interfejs użytkownika Swaggera działa z moimi plikami 2.0, które zaczynają się od „swagger”: „2.0”,

djb

Answer 23

Ponadto z edytora Swagger możesz wyeksportować specyfikację JSON (nie jako YAML, ale jako JSON), a interfejs użytkownika Swagger powinien być w stanie to odczytać. (Uwaga: plik swagger.json musi znajdować się na tym samym hoście / porcie co aplikacja Swagger UI lub musisz włączyć CORS; zobacz

plik

Answer 24

Spędziłem dużo czasu i wypróbowałem wiele różnych rozwiązań - w końcu zrobiłem to w ten sposób:

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

Wystarczy, że ścieżka / to / my / swagger.yaml będzie obsługiwana z tej samej lokalizacji.
(lub użyj nagłówków CORS)

Answer 25

Wielkie dzieki! Użyłem <link rel = "stylesheet" href = " petstore.swagger.io/swagger-ui.css "> <script src = " petstore.swagger.io/swagger-ui-bundle.js "></script >

Erando,

Answer 26

1

Uważam, że jest to najlepsze rozwiązanie, bez żadnej instalacji!

KurioZ7

Answer 27

Niezwykle pomocne. Zaoszczędziłeś dużo czasu.

kalpesh khule

Answer 28

Możesz również pobrać Swagger UI z: https://github.com/swagger-api/swagger-ui , pobrać folder dist, zmodyfikować index.html: zmienić konstruktora

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

w

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

teraz folder dist zawiera wszystko, czego potrzebujesz i może być rozpowszechniany tak, jak jest

Answer 29

2

Spójrz na ten link: http://zircote.com/swagger-php/installation.html

Pobierz plik phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
Zainstaluj Composer https://getcomposer.org/download/
Utwórz plik composer.json
Sklonuj plik swagger-php / library
Clone swagger-ui / library
Utwórz klasy php zasobów i modelu dla interfejsu API
Uruchom plik PHP, aby wygenerować plik json
Podaj ścieżkę do json w api-doc.json
Podaj ścieżkę do api-doc.json w index.php w folderze swagger-ui dist

Jeśli potrzebujesz dodatkowej pomocy, nie wahaj się zapytać.

Syed Raza Mehdi
źródło

1

Czy istnieje edytor online (inny niż edytor swagger), który może to dla mnie wygenerować? Nie chcę dodawać adnotacji do moich interfejsów API PHP, jeśli istnieje prostszy sposób. Problem, który odkryłem, polega na tym, że swagger-editor generuje swagger spec v2.0, a swagger-ui nie obsługuje tego na razie.

Salil

@Salil Wiem tylko, że swagger udostępnia własny edytor on-line, tj. Editor.swagger.wordnik.com Nie znam żadnego innego edytora on-line, jeśli znajdziesz jakiś, podziel się nim z nami, dzięki :)

Syed Raza Mehdi,

Answer 30

1

Czy istnieje edytor online (inny niż edytor swagger), który może to dla mnie wygenerować? Nie chcę dodawać adnotacji do moich interfejsów API PHP, jeśli istnieje prostszy sposób. Problem, który odkryłem, polega na tym, że swagger-editor generuje swagger spec v2.0, a swagger-ui nie obsługuje tego na razie.

Salil

Answer 31

@Salil Wiem tylko, że swagger udostępnia własny edytor on-line, tj. Editor.swagger.wordnik.com Nie znam żadnego innego edytora on-line, jeśli znajdziesz jakiś, podziel się nim z nami, dzięki :)

Syed Raza Mehdi,

Answer 32

Jest mały program Java, który generuje dokumenty (adoc lub md) z pliku 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);

Niestety obsługuje tylko OpenAPI 2.0, ale nie obsługuje OpenAPI 3.0 .

Answer 33

2

W przypadku Swagger API 3.0 generowanie kodu klienta Html2 z internetowego edytora Swagger działa świetnie!

Kumar S
źródło

Answer 34

Zauważyłem, że to narzędzie o nazwie api-html jest bardzo przydatne. Generuje niesamowity interfejs użytkownika HTML5 z wieloma możliwościami.

Istnieją opcje generowania online lub za pośrednictwem narzędzia CLI .

Oto link do wersji demonstracyjnej opartej na „api-html”: Pets-demo

Konwersja specyfikacji Swaggera z formatu JSON do dokumentacji HTML

Odpowiedzi: