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
예쁜 장식 확인
그것은 가지고있다
- Swagger-Editor 의 오른쪽 패널 과 비슷합니다.
- 검색 / 필터
- 스키마 접기
- 라이브 피드백
- 단일 HTML 파일로 출력
Swagger Editor를보고 있는데 미리보기 창을 내보낼 수 있다고 생각했지만 할 수없는 것으로 나타났습니다. 그래서 저는 제 자신의 버전을 썼습니다.
전체 공개 : 나는 도구의 작성자입니다.
GitHub 의 swagger-api / swagger-codegen 프로젝트를 참조하십시오 . 프로젝트 README는이를 사용하여 정적 HTML을 생성하는 방법을 보여줍니다. 정적 html api 문서 생성을 참조하십시오 .
swagger.json을 보려면 Swagger UI를 설치 하고 실행할 수 있습니다. 웹 서버 (GitHub에서 리포지토리를 복제 한 후 dist 폴더)에 배포하고 브라우저에서 Swagger UI를 봅니다. JavaScript 앱입니다.
모든 것이 너무 어렵거나 잘못 문서화되었으므로 다음과 같이 작동 하는 간단한 스크립트 swagger-yaml-to-html.py로이 문제를 해결 했습니다.
python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html
이것은 YAML 용이지만 JSON과 함께 작동하도록 수정하는 것도 간단합니다.
나는 많은 시간을 보냈고 많은 다른 해결책을 시도했다-결국 나는 이렇게했다.
<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 헤더 사용)
You can also download swagger ui from: https://github.com/swagger-api/swagger-ui, take the dist folder, modify index.html: change the constructor
const ui = SwaggerUIBundle({
url: ...,
into
const ui = SwaggerUIBundle({
spec: YOUR_JSON,
now the dist folder contains all what you need and can be distributed as is
Give a look at this link : http://zircote.com/swagger-php/installation.html
- Download phar file https://github.com/zircote/swagger-php/blob/master/swagger.phar
- Install Composer https://getcomposer.org/download/
- Make composer.json
- Clone swagger-php/library
- Clone swagger-ui/library
- Make Resource and Model php classes for the API
- Execute the PHP file to generate the json
- Give path of json in api-doc.json
- Give path of api-doc.json in index.php inside swagger-ui dist folder
If you need another help please feel free to ask.
There's a small Java program which generates docs (adoc or md) from a yaml file.
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);
Unfortunately it only supports OpenAPI 2.0 but not OpenAPI 3.0.
'Nice programing' 카테고리의 다른 글
| 방랑자는 기본적으로 안전하지 않습니까? (0) | 2020.11.01 |
|---|---|
| AngularJS 문서가 모델 지시어에 점을 사용하지 않는 이유는 무엇입니까? (0) | 2020.11.01 |
| Electron (Atom Shell) 애플리케이션에서 사용자 설정을 저장할 위치는? (0) | 2020.11.01 |
| ASP.NET 애플리케이션을 단위 테스트 할 때 web.config를 사용하는 방법 (0) | 2020.11.01 |
| 왜 (0) | 2020.11.01 |