Swagger 사양 JSON을 HTML 문서로 변환

PHP로 작성된 일부 REST API의 경우 Swagger 문서 를 작성하라는 요청을 받았으며 기존 API에 주석을 추가하고 문서 를 작성 하는 쉬운 방법을 몰랐기 때문에 지금은 이 편집기 를 사용하여 일부를 생성했습니다.

해당 편집기를 사용하여 만든 JSON 및 YAML 파일을 저장했으며 이제 최종 대화 형 Swagger 문서를 만들어야합니다 (이 문장은 순진하고 모호하게 들릴 수 있음).

누군가 Swagger JSON 사양 파일을 실제 Swagger 문서로 변환하는 방법을 알려주시겠습니까?

저는 Windows 플랫폼을 사용하고 있으며 Ant / Maven에 대해 아무것도 모릅니다.

swagger-codegen이 작업을 수행 할 도구를 찾을 때 만족스럽지 않아 직접 작성했습니다. bootprint-swagger 살펴보기

비교되는 주요 목표 swagger-codegen는 쉬운 설정을 제공하는 것입니다 (nodejs가 필요하지만). 또한 부트 프린트 프로젝트 의 핵심 기능인 자신의 요구에 맞게 스타일과 템플릿을 쉽게 적용 할 수 있어야합니다.

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

예쁜 장식 확인

그것은 가지고있다

1. Swagger-Editor 의 오른쪽 패널 과 비슷합니다.
2. 검색 / 필터
3. 스키마 접기
4. 라이브 피드백
5. 단일 HTML 파일로 출력

Swagger Editor를보고 있는데 미리보기 창을 내보낼 수 있다고 생각했지만 할 수없는 것으로 나타났습니다. 그래서 저는 제 자신의 버전을 썼습니다.

전체 공개 : 나는 도구의 작성자입니다.

모든 것이 너무 어렵거나 잘못 문서화되었으므로 다음과 같이 작동 하는 간단한 스크립트 swagger-yaml-to-html.py로이 문제를 해결 했습니다.

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

이것은 YAML 용이지만 JSON과 함께 작동하도록 수정하는 것도 간단합니다.

GitHub 의 swagger-api / swagger-codegen 프로젝트를 참조하십시오 . 프로젝트 README는이를 사용하여 정적 HTML을 생성하는 방법을 보여줍니다. 정적 html api 문서 생성을 참조하십시오 .

swagger.json을 보려면 Swagger UI를 설치 하고 실행할 수 있습니다. 웹 서버 (GitHub에서 리포지토리를 복제 한 후 dist 폴더)에 배포하고 브라우저에서 Swagger UI를 봅니다. JavaScript 앱입니다.

나는 많은 시간을 보냈고 많은 다른 해결책을 시도했다-결국 나는 이렇게했다.

<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 헤더 사용)

https://github.com/swagger-api/swagger-ui 에서 swagger ui를 다운로드 하고 dist 폴더를 가져 오고 index.html을 수정합니다. 생성자 변경

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

으로

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

이제 dist 폴더는 필요한 모든 것을 포함하고있는 그대로 배포 할 수 있습니다.

이 링크를보십시오 : http://zircote.com/swagger-php/installation.html

1. phar 파일 https://github.com/zircote/swagger-php/blob/master/swagger.phar 다운로드
2. Composer 설치 https://getcomposer.org/download/
3. composer.json 만들기
4. swagger-php / library 복제
5. swagger-ui / library 복제
6. API 용 리소스 및 모델 PHP 클래스 만들기
7. PHP 파일을 실행하여 json 생성
8. api-doc.json에서 json의 경로 제공
9. swagger-ui dist 폴더 내의 index.php에서 api-doc.json의 경로 제공

다른 도움이 필요하면 언제든지 문의하십시오.

yaml 파일에서 문서 (adoc 또는 md)를 생성 하는 작은 Java 프로그램 이 있습니다.

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 은 지원 하지 않습니다 .

Swagger API 3.0의 경우 온라인 Swagger 편집기에서 Html2 클라이언트 코드를 생성하는 것이 좋습니다.

api-html 이라는이 도구가 매우 유용하다는 것을 알았습니다 . 많은 가능성을 가진 멋진 html5 UI를 생성하고 있습니다.

온라인 또는 CLI 도구를 통해 생성하는 옵션이 있습니다 .

다음은 "api-html"의 데모 빌드에 대한 링크입니다. pets-demo