Konwersja specyfikacji Swaggera z formatu JSON do dokumentacji HTML

88

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.

yaml  swagger  swagger-php 
— Salil
źródło
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

Odpowiedzi:

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

Spójrz na ładny łup

To ma

  1. Podobnie wygląda jak prawy panel edytora Swagger
  2. Wyszukaj / Filtruj
  3. Schemat składania
  4. Informacje zwrotne na żywo
  5. 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
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
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
14

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

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

— Kris Randall
źródło
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,
1
Uważam, że jest to najlepsze rozwiązanie, bez żadnej instalacji!
— KurioZ7
Niezwykle pomocne. Zaoszczędziłeś dużo czasu.
— kalpesh khule
7

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

— user1928596
źródło
2

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

  1. Pobierz plik phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
  2. Zainstaluj Composer https://getcomposer.org/download/
  3. Utwórz plik composer.json
  4. Sklonuj plik swagger-php / library
  5. Clone swagger-ui / library
  6. Utwórz klasy php zasobów i modelu dla interfejsu API
  7. Uruchom plik PHP, aby wygenerować plik json
  8. Podaj ścieżkę do json w api-doc.json
  9. 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,
2

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 .

— Erando
źródło
2

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

— Kumar S
źródło
Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.