Chuyển đổi thông số kỹ thuật Swagger JSON sang tài liệu HTML

88

Đối với một số API REST được viết bằng PHP, tôi được yêu cầu tạo tài liệu Swagger và vì tôi không biết bất kỳ cách dễ dàng nào để thêm chú thích vào các API hiện có đó và tạo tài liệu như vậy, tôi đã sử dụng trình chỉnh sửa này để tạo một số tài liệu .

Tôi đã lưu các tệp JSON và YAML được tạo bằng trình chỉnh sửa đó và bây giờ tôi cần tạo tài liệu Swagger tương tác cuối cùng (tuyên bố này nghe có vẻ ngây thơ và mơ hồ).

Ai đó có thể vui lòng cho tôi biết cách tôi có thể chuyển đổi tệp đặc tả Swagger JSON thành tài liệu Swagger thực tế không?

Tôi đang sử dụng nền tảng Windows và không biết gì về Ant / Maven.

yaml swagger swagger-php

— Salil
nguồn

tôi đã thử [ github.com/wordnik/swagger-ui](Swagger UI) nhưng nó không hiển thị json của tôi. cảnh báo duy nhất được hiển thị là "API này đang sử dụng phiên bản Swagger không được dùng nữa! Vui lòng xem github.com/wordnik/swagger-core/wiki để biết thêm thông tin".

— Salil

43

Tôi không hài lòng với swagger-codegenkhi tôi đang tìm kiếm một công cụ để làm điều này, vì vậy tôi đã viết của riêng tôi. Hãy xem bootprint-swagger

Mục tiêu chính được so sánh với swagger-codegenlà cung cấp một thiết lập dễ dàng (mặc dù bạn sẽ cần nodejs). Và phải dễ dàng điều chỉnh kiểu dáng và mẫu theo nhu cầu của riêng bạn, đây là một chức năng cốt lõi của dự án bootprint

— Nils Knappmeier
nguồn

9

Cảnh báo: Kể từ tháng 11/2016, tác giả của bootprint-swagger dường như đã từ bỏ dự án. swagger-codegen vẫn được hỗ trợ tốt.

— Brent Matzelle

22

Tôi là tác giả và văn bản cho biết: "Tôi rất tiếc phải nói rằng tôi sẽ không thể phát triển các tính năng mới cho dự án này trong tương lai gần. Nhưng: Tôi có thể sẽ thảo luận và hợp nhất các yêu cầu kéo, và xuất bản các phiên bản mới. " Bạn có thể gọi đó là bị bỏ rơi, tôi sẽ gọi nó là "tạm giữ". Tôi cũng sẽ mời bất cứ ai quan tâm đến việc đóng góp cho dự án.

— Nils Knappmeier

1

Tìm thấy điều đó spectacletạo ra tài liệu đẹp hơn nhiều từ JSON swagger

— foreverthinker

Sau rất nhiều đấu tranh, tôi thấy công cụ này rất hữu ích: api-html

— Asfandiyar Khan

57

Cố gắng sử dụng redoc-cli .

Tôi đã sử dụng bootprint-openapi mà tôi đã tạo ra một loạt các file ( bundle.js, bundle.js.map, index.html, main.cssvà main.css.map) và sau đó bạn có thể chuyển đổi nó thành một đơn .htmltập tin sử dụng html-inline để tạo ra một đơn giản index.htmltập tin.

Sau đó, tôi thấy redoc-cli rất dễ sử dụng và đầu ra thực sự-2 tuyệt vời, một tệp index.html duy nhất và đẹp .

Cài đặt :

npm install -g redoc-cli

Cách sử dụng :

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

— Vikasdeep Singh
nguồn

8

Công cụ này thực sự tạo ra đầu ra đẹp nhất trong tất cả các công cụ được đề cập.

— Jakub Moravec,

1

Đây là cái tốt nhất cho đến nay của imo và vì chúng tôi đang xây dựng cái này cho các nhà phát triển đang sử dụng máy tính để bàn nên kích thước đầu ra không phải là vấn đề.

— milosmns

3

Sử dụng tên tệp thực thi trực tiếp không phải lúc nào cũng hoạt động, việc thực thi bằng npx redoc-cli ...sẽ đáng tin cậy hơn.

— Crouching Kitten,

2

Đầu ra cực đẹp. Cảm ơn đã gợi ý.

— Sahil Jain

1

Đây là một công cụ tuyệt vời !! Cảm ơn Vikas sâu sắc vì lời đề nghị tuyệt vời anh em !! Chắc chắn là cách tốt hơn và ít vụng về hơn bootstrap-openapi!

— Chaturvedi Saurabh

19

Kiểm tra khá-swag

Nó có

Tương tự như bảng điều khiển bên phải của Swagger-Editor
Tìm kiếm / Lọc
Gấp giản đồ
Phản hồi trực tiếp
Đầu ra dưới dạng một tệp html duy nhất

Tôi đã xem xét Swagger Editor và nghĩ rằng nó có thể xuất khung xem trước nhưng hóa ra không thể. Vì vậy, tôi đã viết phiên bản của riêng tôi về nó.

Tiết lộ đầy đủ: Tôi là tác giả của công cụ.

— TLJ
nguồn

1

Tôi thấy khá-swag là một công cụ đơn giản và lý tưởng, với các điểm nhập CLI và API thích hợp. Khiếu nại duy nhất của tôi (và là điều buộc tôi phải đối mặt với sự phức tạp của swagger-ui) là nó không xử lý chính xác thành phần / phần mở rộng đối tượng. Bất kỳ việc sử dụng nào allOftrong tài liệu đều tạo ra undefined, ngay cả trong các trường hợp đơn giản nhất ("hợp nhất" một đối tượng, tương đương với việc không sử dụng allOf).

— HonoredMule

3

Chỉ allOfgiới thiệu tính năng cho bạn. Kiểm tra nó ra.

— TLJ

2

Không xuất hiện để hỗ trợ Swagger / OpenAPI V3

— SeinopSys

18

Mọi thứ quá khó khăn hoặc được ghi chép không tốt nên tôi đã giải quyết vấn đề này bằng một tập lệnh đơn giản swagger-yaml-to-html.py , hoạt động như thế này

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

Điều này dành cho YAML nhưng việc sửa đổi nó để hoạt động với JSON cũng rất nhỏ.

— oseiskar
nguồn

Đây là vàng nguyên chất!

— zemirco

16

Xem dự án swagger-api / swagger-codegen trên GitHub; dự án README chỉ ra cách sử dụng nó để tạo HTML tĩnh. Xem Tạo tài liệu api html tĩnh .

Nếu bạn muốn xem swagger.json, bạn có thể cài đặt giao diện người dùng Swagger và chạy nó. Bạn chỉ cần triển khai nó trên một máy chủ web (thư mục dist sau khi bạn sao chép repo từ GitHub) và xem giao diện người dùng Swagger trong trình duyệt của mình. Đó là một ứng dụng JavaScript.

— djb
nguồn

Cảm ơn. Vấn đề của tôi là swagger-ui không chấp nhận thông số kỹ thuật 2.0. Tuy nhiên, đây có vẻ là câu trả lời đơn giản nhất, vì vậy tôi sẽ chấp nhận điều này (hiện tại).

— Salil

Các công cụ Swagger vẫn đang phát triển cho phiên bản 2.0. Tuy nhiên, tôi nhận thấy giao diện người dùng Swagger không hoạt động cho các tệp 2.0 của tôi bắt đầu bằng "swagger": "2.0",

— djb

Ngoài ra, từ Swagger Editor, bạn có thể xuất thông số JSON (không phải dưới dạng YAML mà là JSON) và giao diện người dùng Swagger sẽ có thể đọc được thông số đó. (Lưu ý: swagger.json phải ở trên cùng một máy chủ / cổng với ứng dụng Swagger UI hoặc bạn phải bật CORS; xem README.md trong Swagger Editor trên GitHub

— djb

14

Tôi đã dành rất nhiều thời gian và thử rất nhiều giải pháp khác nhau - cuối cùng tôi đã làm theo cách này:

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

Bạn chỉ cần có đường dẫn / đến / của tôi / swagger.yaml được phân phát từ cùng một vị trí.
(hoặc sử dụng tiêu đề CORS)

— Kris Randall
nguồn

Thật sự cảm ơn! Tôi đã sử dụng <link rel = "stylesheet" href = " petstore.swagger.io/swagger-ui.css "> <script src = " petstore.swagger.io/swagger-ui-bundle.js "></script >

— Erando 28/09/18

1

Tôi thấy đây là giải pháp tốt nhất, không cần cài đặt bất cứ thứ gì!

— KurioZ7

Cực kỳ hữu ích. Bạn đã tiết kiệm rất nhiều thời gian.

— kalpesh khule

7

Bạn cũng có thể tải xuống swagger ui từ: https://github.com/swagger-api/swagger-ui , lấy thư mục dist, sửa đổi index.html: thay đổi hàm tạo

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

thành

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

bây giờ thư mục dist chứa tất cả những gì bạn cần và có thể được phân phối như hiện tại

— người dùng1928596
nguồn

2

Hãy xem liên kết này: http://zircote.com/swagger-php/installation.html

Tải xuống tệp phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
Cài đặt Composer https://getcomposer.org/download/
Make composer.json
Sao chép swagger-php / thư viện
Sao chép swagger-ui / thư viện
Tạo các lớp php Tài nguyên và Mô hình cho API
Thực thi tệp PHP để tạo json
Cung cấp đường dẫn của json trong api-doc.json
Cung cấp đường dẫn của api-doc.json trong index.php bên trong thư mục swagger-ui dist

Nếu bạn cần trợ giúp khác, vui lòng hỏi.

— Syed Raza Mehdi
nguồn

1

Có trình soạn thảo trực tuyến nào (ngoài swagger-editor) có thể tạo điều này cho tôi không? Tôi không muốn chú thích các API PHP của mình nếu có một cách đơn giản hơn. Vấn đề, tôi đã tìm ra là swagger-editor tạo ra swagger spec v2.0 và swagger-ui không xử lý điều đó kể từ bây giờ.

— Salil

@Salil tất cả những gì tôi biết là swagger cung cấp trình chỉnh sửa trực tuyến của riêng nó, tức là editor.swagger.wordnik.com. Tôi không biết về bất kỳ trình chỉnh sửa trực tuyến nào khác, nếu bạn thấy bất kỳ hãy chia sẻ nó với chúng tôi, cảm ơn :)

— Syed Raza Mehdi

2

Có một chương trình Java nhỏ tạo tài liệu (adoc hoặc md) từ tệp 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);

Thật không may, nó chỉ hỗ trợ OpenAPI 2.0 chứ không phải OpenAPI 3.0 .

— Erando
nguồn

2

Đối với Swagger API 3.0, việc tạo mã ứng dụng Html2 từ Swagger Editor trực tuyến phù hợp với tôi!

— Kumar S
nguồn

1

Tôi đã tìm thấy công cụ có tên api-html này rất hữu ích. Nó tạo ra một giao diện người dùng html5 tuyệt vời với nhiều khả năng.

Có các tùy chọn để tạo trực tuyến hoặc thông qua công cụ cli .

Đây là một liên kết đến bản dựng demo trên "api-html": Pet-demo

— Asfandiyar Khan
nguồn