PHP로 작성된 일부 REST API의 경우 Swagger 문서 를 작성하라는 요청을 받았으며 기존 API에 주석을 추가하고 문서 를 작성 하는 쉬운 방법을 몰랐기 때문에 지금은 이 편집기 를 사용하여 일부를 생성했습니다.
해당 편집기를 사용하여 만든 JSON 및 YAML 파일을 저장했으며 이제 최종 대화 형 Swagger 문서를 만들어야합니다 (이 문장은 순진하고 모호하게 들릴 수 있음).
누군가 Swagger JSON 사양 파일을 실제 Swagger 문서로 변환하는 방법을 알려주시겠습니까?
저는 Windows 플랫폼을 사용하고 있으며 Ant / Maven에 대해 아무것도 모릅니다.
답변:
swagger-codegen이 작업을 수행 할 도구를 찾을 때 만족스럽지 않아 직접 작성했습니다. bootprint-swagger 살펴보기
비교되는 주요 목표 swagger-codegen는 쉬운 설정을 제공하는 것입니다 (nodejs가 필요하지만). 또한 부트 프린트 프로젝트 의 핵심 기능인 자신의 요구에 맞게 스타일과 템플릿을 쉽게 적용 할 수 있어야합니다.
spectacle훨씬 더 생긴 자신감 JSON에서 문서 생성
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
npx redoc-cli ...이 더 신뢰할 수 있습니다.
예쁜 장식 확인
그것은 가지고있다
Swagger Editor를보고 있는데 미리보기 창을 내보낼 수 있다고 생각했지만 할 수없는 것으로 나타났습니다. 그래서 저는 제 자신의 버전을 썼습니다.
전체 공개 : 나는 도구의 작성자입니다.
allOf문서가 생산에 undefined심지어 간단한 시나리오에서, (하나의 객체를 "병합", 상응 사용하지 않으려면 allOf모두에서).
allOf기능입니다. 확인 해봐.
모든 것이 너무 어렵거나 잘못 문서화되었으므로 다음과 같이 작동 하는 간단한 스크립트 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
다른 도움이 필요하면 언제든지 문의하십시오.
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 은 지원 하지 않습니다 .