Swagger 2 문 서 를 HTML 이나 markdown 등 형식 으로 오프라인 으로 내 보 냅 니 다.

인터넷 에는'swagger 2 를 사용 하여 API 문 서 를 구축 합 니 다'라 는 글 이 많 습 니 다.이 문 서 는 온라인 문서 로 HTTP 로 접근 해 야 합 니 다.그러나 우리 가 일상적으로 swagger 인터페이스 문 서 를 사용 할 때,때때로 인터페이스 문 서 를 오프라인 으로 접근 해 야 한다.예 를 들 어 문 서 를 html,markdown 형식 으로 내 보 내 는 것 이다.또한 저 희 는 응용 시스템 과 swagger 인터페이스 문서 가 같은 서 비 스 를 사용 하 는 것 을 원 하지 않 고 HTML 을 내 보 낸 후에 따로 배치 하 는 것 을 원 합 니 다.이렇게 하면 인터페이스 문서 에 대한 방문 이 업무 시스템 에 영향 을 주지 않 고 어느 정도 인터페이스 문서 의 안전성 을 향상 시 켰 습 니 다.핵심 적 인 실현 과정 은:
4.567917.swagger 2 인터페이스 문서 가 있 는 응용 프로그램 에서 swagger 2 markup 을 이용 하여 인터페이스 문 서 를 adoc 파일 로 내 보 내 고 markdown 파일 도 내 보 낼 수 있 습 니 다

그리고 adoc 파일 을 정적 html 형식 으로 변환 하면 html 를 nginx 또는 다른 웹 응용 용기 에 발표 하여 접근 할 수 있 습 니 다(본 고 는 html 정적 배 치 를 말 하지 않 고 HTML 내 보 내기 만 말 합 니 다)

메모:adoc 는 파일 형식 입 니 다.제 가 잘못 쓴 것 이 아 닙 니 다.doc 파일 도 아니 고 docx 파일 도 아니 고
1.maven 의존 라 이브 러 리
swagger 2 가 통합 되 어 있 는 응용 프로그램 에서 maven 좌 표를 통 해 관련 의존 라 이브 러 리 를 도입 합 니 다.pom.xml 코드 는 다음 과 같 습 니 다.

<dependency>
 <groupId>io.github.swagger2markup</groupId>
 <artifactId>swagger2markup</artifactId>
 <version>1.3.1</version>
</dependency>
<dependency>
 <groupId>io.swagger</groupId>
 <artifactId>swagger-core</artifactId>
 <version>1.5.16</version>
</dependency>
<dependency>
 <groupId>io.swagger</groupId>
 <artifactId>swagger-models</artifactId>
 <version>1.5.16</version>
</dependency>

swagger2markup 은 swagger 2 온라인 인터페이스 문 서 를 html,markdown,adoc 등 형식 문서 로 내 보 내 고 정적 배치 나 오프라인 읽 기 에 사용 합 니 다.그 중 첫 번 째 Maven 좌 표 는 필수 입 니 다.다음 두 개의 maven 좌 표 는 다음 코드 를 실행 하 는 과정 에서 다음 그림 의 ERROR 을 보고 하거나 import 가 불가능 할 때 사용 합 니 다.

이상 이 발생 한 원인 은 이미 github 의 issues 에 설명 되 었 습 니 다.swagger-core 버 전 을 사용 하면 1.5.11 이상 이 고 swagger-models 버 전이 1.5.11 보다 적 으 면 이상 이 발생 할 수 있 습 니 다.그래서 우 리 는 이 두 개의 jar 를 현저하게 도입 하여 swagger 2 가 기본적으로 도입 한 두 개의 jar 를 교체 합 니 다.

2.adoc 형식 파일 생 성
다음 코드 는 인 코딩 을 통 해 이 루어 진 adoc 형식 파일 을 만 드 는 방식 입 니 다.

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class DemoApplicationTests {
 @Test
 public void generateAsciiDocs() throws Exception {
  //   Ascii  
  Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.ASCIIDOC) //      
    .withOutputLanguage(Language.ZH) //            
    .withPathsGroupedBy(GroupBy.TAGS)
    .withGeneratedExamples()
    .withoutInlineSchema()
    .build();

  Swagger2MarkupConverter.from(new URL("http://localhost:8888/v2/api-docs"))
    .withConfig(config)
    .build()
    .toFile(Paths.get("src/main/resources/docs/asciidoc"));
 }
}

RunWith 주해 와 SpringBootTest 주 해 를 사용 하여 응용 서비스 용 기 를 시작 합 니 다.SpringBootTest.WebEnvironment.DEFINED_PORT 는 하나의 포트 를 무 작위 로 사용 하여 테스트 하 는 것 이 아니 라 application.yml 이 정의 하 는 포트 를 사용 하 는 것 이 중요 하 다 고 밝 혔 다.
Swagger2markup Config 는 파일 의 형식 과 파일 의 자연 언어 등 출력 파일 의 설정 입 니 다.
Swagger2markupConverter 의 from 은 자원 내 보 내기 의 원본(JSON 형식)으로 어떤 HTTP 서 비 스 를 사용 하 는 지 표시 합 니 다.이 링크 를 직접 방문 해 보 세 요.8888 은 나의 서비스 포트 입 니 다.당신 의 응용 설정 에 따라 수정 해 야 합 니 다.
toFile 은 파일 이 저 장 된 위 치 를 내 보 낼 것 이 며 접미사 이름 을 붙 이지 않 아 도 됩 니 다.toFolder 를 사용 하여 파일 이 저 장 된 경 로 를 내 보 낼 수도 있 습 니 다.두 가지 차이 점 은 toFolder 를 사용 하여 파일 디 렉 터 리 로 내 보 내 고 태그 TAGS 에 따라 분 류 된 여러 파일 을 내 보 내 는 것 입 니 다.toFile 을 사용 하면 파일(toFolder 여러 파일 의 집합)을 내 보 냅 니 다.

@Test
public void generateMarkdownDocsToFile() throws Exception {
 //   Markdown    
 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
   .withMarkupLanguage(MarkupLanguage.MARKDOWN)
   .withOutputLanguage(Language.ZH)
   .withPathsGroupedBy(GroupBy.TAGS)
   .withGeneratedExamples()
   .withoutInlineSchema()
   .build();

 Swagger2MarkupConverter.from(new URL("http://localhost:8888/v2/api-docs"))
   .withConfig(config)
   .build()
   .toFile(Paths.get("src/main/resources/docs/markdown"));
}

위의 이 코드 는 markdown 형식 인터페이스 파일 을 만 드 는 코드 입 니 다.위의 2 단 단원 테스트 코드 를 실행 하면 대응 하 는 형식의 인터페이스 파일 을 생산 할 수 있다.
maven 플러그 인 을 통 해 adoc 와 markdown 형식의 인터페이스 파일 을 만 드 는 방법 도 있 습 니 다.필 자 는 이런 방식 을 자주 사용 하지 않 고 코드 생 성 방식 으로 유연 하 게 설정 하지 않 았 으 며 많은 설정 을 pom.xml 에 넣 으 면 비대 함 을 느 꼈 다.그래도 소개 하 겠 습 니 다.우선 Maven 플러그 인 swagger2markup-maven-plugin 을 설정 합 니 다.

<plugin>
 <groupId>io.github.swagger2markup</groupId>
 <artifactId>swagger2markup-maven-plugin</artifactId>
 <version>1.3.1</version>
 <configuration>
  <swaggerInput>http://localhost:8888/v2/api-docs</swaggerInput><!---swagger-api-json  -->
  <outputDir>src/main/resources/docs/asciidoc</outputDir><!---    -->
  <config>
   <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage><!--    -->
  </config>
 </configuration>
</plugin>

그리고 플러그 인 을 실행 하면 됩 니 다.다음 그림:

3.maven 플러그 인 을 통 해 HTML 문서 생 성

<plugin>
 <groupId>org.asciidoctor</groupId>
 <artifactId>asciidoctor-maven-plugin</artifactId>
 <version>1.5.6</version>
 <configuration>
   <!--asciidoc    -->
  <sourceDirectory>src/main/resources/docs</sourceDirectory>
  <!---  html   -->
  <outputDirectory>src/main/resources/html</outputDirectory>
  <backend>html</backend>
  <sourceHighlighter>coderay</sourceHighlighter>
  <attributes>
   <!--     -->
   <toc>left</toc>
   <!--     -->
   <!--<toclevels>3</toclevels>-->
   <!--       -->
   <sectnums>true</sectnums>
  </attributes>
 </configuration>
</plugin>

adoc 의 sourceDirectory 경 로 는 세 번 째 소절 에서 생 성 된 adoc 파일 경로 와 일치 해 야 합 니 다.그리고 다음 그림 방식 으로 플러그 인 을 실행 합 니 다.

HTMl 인터페이스 문서 의 효 과 는 다음 과 같 습 니 다.HTML 인터페이스 문서 가 있 으 면 다른 형식의 문서 로 바 꾸 기 가 너무 편리 하고 사용 할 수 있 는 도구 가 많 습 니 다.여 기 는 일일이 소개 하지 않 겠 습 니 다.

총결산
위 에서 설명 한 것 은 스 와 거 2 문 서 를 HTML 이나 markdown 등 형식 으로 오프라인 으로 내 보 내 는 것 입 니 다.도움 이 되 셨 으 면 좋 겠 습 니 다.궁금 한 점 이 있 으 시 면 메 시 지 를 남 겨 주세요.여기 서도 저희 사이트 에 대한 여러분 의 지지 에 감 사 드 립 니 다!
만약 당신 이 본문 이 당신 에 게 도움 이 된다 고 생각한다 면,전 재 를 환영 합 니 다.번 거 로 우 시 겠 지만 출처 를 밝 혀 주 십시오.감사합니다!