[yaml] Swagger 사양 JSON을 HTML 문서로 변환

Program / 글쓴이

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 폴더는 필요한 모든 것을 포함하고있는 그대로 배포 할 수 있습니다.