swagger导出离线文档
参考:
https://blog.csdn.net/ii19910410/article/details/90031310
https://www.cnblogs.com/james-roger/p/13183661.html
https://www.cnblogs.com/jpfss/p/11438606.html
https://www.cnblogs.com/hanxue112253/p/10983483.html
https://blog.csdn.net/u012888052/article/details/115208796
swagger的HTML文档已经很完美了,但总有一些时候,需要静态的文件文档。这时候就需要配置一些插件。
一、swagger相关的依赖pom
<!-- swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.5.0</version> </dependency> <!--swagger-ui--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.5.0</version> </dependency> <!-- swagger导出PDF/HTML所需依赖 --> <dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.1</version> </dependency>
二、maven插件
在maven-build-plugins下面增加两个插件
<plugin> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup-maven-plugin</artifactId> <version>1.2.0</version> <configuration> <!--此处端口一定要是当前项目启动所用的端口--> <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput> <!--生成多个文件--> <!-- <outputDir>src/docs/asciidoc/generated</outputDir>--> <!--生成单个文件--> <outputFile>src/docs/asciidoc/api</outputFile> <config> <!-- 除了ASCIIDOC之外,还有MARKDOWN和CONFLUENCE_MARKUP可选,下面生成HTML和PDF的的插件依赖ASCIIDOC格式 --> <swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage> </config> </configuration> </plugin> <plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.3</version> <!-- Include Asciidoctor PDF for pdf generation --> <dependencies> <dependency> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctorj-pdf</artifactId> <version>1.5.0-alpha.10.1</version> </dependency> <dependency> <groupId>org.jruby</groupId> <artifactId>jruby-complete</artifactId> <version>1.7.21</version> </dependency> </dependencies> <!-- Configure generic document generation settings --> <configuration> <!-- 对应上面插件的outputdir--> <!-- <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>--> <!-- 对应上面插件的outputfile--> <sourceDirectory>src/docs/asciidoc</sourceDirectory> <sourceDocumentName>api.adoc</sourceDocumentName> <sourceHighlighter>coderay</sourceHighlighter> <attributes> <toc>left</toc> </attributes> </configuration> <!-- Since each execution can only handle one backend, run separate executions for each desired output type --> <executions> <execution> <id>output-html</id> <phase>generate-resources</phase> <goals> <goal>process-asciidoc</goal> </goals> <configuration> <backend>html5</backend> <outputDirectory>src/docs/asciidoc/html</outputDirectory> </configuration> </execution> <!-- pdf中文有乱码,目前不太好用--> <execution> <id>output-pdf</id> <phase>generate-resources</phase> <goals> <goal>process-asciidoc</goal> </goals> <configuration> <backend>pdf</backend> <outputDirectory>src/docs/asciidoc/pdf</outputDirectory> </configuration> </execution> </executions> </plugin>
三、swagger配置文件(可选)
有时候发现swagger生成的接口文档里有一些springboot自己的接口,这些是调试用的,对外根本不需要,怎么可以从文档里把这些去掉呢,就需要swagger配置类指定我需要的接口的所在包,这样其他的接口就不会出现了。
@EnableSwagger2 @Configuration public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("cc.group.articid.controller")) .paths(PathSelectors.any()) .build(); } }
四、maven命令
1.mvn swagger2markup:convertSwagger2markup
2.mvn generate-resources
第一个插件生成adoc文件,也可以选择生成md文件
第二个插件需要依赖第一个插件的adoc文件,PDF中文会有乱码,我是用上一步的md文件导出的PDF,也很方便
还有如果喜欢HTML的文件,第二个插件会生成一个HTML文件,也很方便。