碼上歡樂
相關內容    簡體    繁體

項目工具三：Swagger導出離線版HTML5和PDF格式api文檔

本文轉載自   查看原文   2020-01-21 14:25   2668    項目管理

之前的文章講解了swagger2注解的用法以及實例演示，本篇文章介紹一下如何使用swagger2導出離線版的api文檔，分為兩種格式一個是HTML5一個是PDF。對象屬性、接口說明、測試用例都可以導出來方便開發人員很清楚的了解接口！

相關版本

  1. Springboot版本：1.5.10.RELEASE

  2. swagger2版本：2.6.1

  3. maven版本：3.2.5

  4. JDK版本：8

  5. IDEA版本：2017.2.6
    大家自己測試的時候如果不成功盡量和我版本保持一致。

index.adoc配置

 

include::{generated}/overview.adoc[]
include::{generated}/definitions.adoc[]
include::{generated}/paths.adoc[]

pom.xml配置

pom里面不比之前需要多配置一些東西，這個是大家需要注意的。

properties配置：

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <java.version>1.8</java.version>

    <snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
    <asciidoctor.input.directory>${project.basedir}/docs/asciidoc</asciidoctor.input.directory>
    <generated.asciidoc.directory>${project.build.directory}/asciidoc</generated.asciidoc.directory>
    <asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
    <asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
</properties>

dependencies依賴配置：

<dependencies>

    <!--fastjson依賴-->
    <dependency>
	<groupId>com.alibaba</groupId>
	<artifactId>fastjson</artifactId>
	<version>1.2.46</version>
    </dependency>

    <!--spring-boot依賴-->
    <dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter</artifactId>
    </dependency>

    <!--測試依賴-->
    <dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-test</artifactId>
	<scope>test</scope>
    </dependency>

    <!--web支持-->
    <dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!--swagger2依賴-->
    <dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.6.1</version>
    </dependency>

    <!--swagger2-ui依賴-->
    <dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.6.1</version>
    </dependency>

    <!--離線文檔-->
    <dependency>
	<groupId>org.springframework.restdocs</groupId>
	<artifactId>spring-restdocs-mockmvc</artifactId>
	<version>1.1.2.RELEASE</version>
	<scope>test</scope>
    </dependency>

    <!--生成靜態文檔-->
    <dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-staticdocs</artifactId>
	<version>2.6.1</version>
    </dependency>

    <!--lombok依賴-->
    <dependency>
	<groupId>org.projectlombok</groupId>
	<artifactId>lombok</artifactId>
	<version>1.16.20</version>
    </dependency>

</dependencies>

plugins插件配置：

<build>
    <plugins>
	<!--<plugin>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>-->
	<!--Maven通過Maven Surefire Plugin插件執行單元測試-->
	<plugin>
	    <groupId>org.apache.maven.plugins</groupId>
	    <artifactId>maven-surefire-plugin</artifactId>
	</plugin>
	<!--通過Asciidoctor使得asciidoc生成其他的文檔格式，例如：PDF 或者HTML5-->
	<plugin>
	    <groupId>org.asciidoctor</groupId>
	    <artifactId>asciidoctor-maven-plugin</artifactId>
	    <version>1.5.3</version>
	    <!--生成PDF-->
	    <dependencies>
		<dependency>
		    <groupId>org.asciidoctor</groupId>
		    <artifactId>asciidoctorj-pdf</artifactId>
		    <version>1.5.0-alpha.14</version>
		</dependency>
	        <!-- Comment this section to use the default jruby artifact provided by the plugin -->
	        <dependency>
	            <groupId>org.jruby</groupId>
		    <artifactId>jruby-complete</artifactId>
		    <version>1.7.21</version>
	        </dependency>
	    </dependencies>

	    <!--文檔生成配置-->
	    <configuration>
	        <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
	        <sourceDocumentName>index.adoc</sourceDocumentName>
	        <attributes>
		    <doctype>book</doctype>
		    <toc>left</toc>
		    <toclevels>3</toclevels>
		    <numbered></numbered>
		    <hardbreaks></hardbreaks>
		    <sectlinks></sectlinks>
		    <sectanchors></sectanchors>
		    <generated>${generated.asciidoc.directory}</generated>
	        </attributes>
	    </configuration>
	    <!--因為每次執行只能處理一個后端，所以對於每個想要的輸出類型，都是獨立分開執行-->
	    <executions>
	        <!--html5-->
	        <execution>
		    <id>output-html</id>
		    <phase>test</phase>
		    <goals>
		        <goal>process-asciidoc</goal>
		    </goals>
		    <configuration>
		        <backend>html5</backend>
		        <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
		    </configuration>
	        </execution>
	        <!--pdf-->
	        <execution>
		    <id>output-pdf</id>
		    <phase>test</phase>
		    <goals>
		        <goal>process-asciidoc</goal>
		    </goals>
		    <configuration>
		        <backend>pdf</backend>
		        <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
		    </configuration>
	        </execution>
	    </executions>
        </plugin>
    </plugins>
</build>

Swagger2Config配置類

public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.czq.offline.controller"))
                    .paths(PathSelectors.any())
                    .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger構建api文檔,可以導出離線的HTML和PDF文檔")
                .description("簡單優雅的restfun風格")
//                .termsOfServiceUrl("https://blog.csdn.net/moyanxiaoq")
                .contact("chenzhiq")
                .version("1.0")
                .build();
    }
}

User實體類

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(description="用戶的實體對象")
public class User {

    /**
     *id
     */
    @ApiModelProperty(value="用戶id",name="id",required=true)
    private String id;

    /**
     *名字
     */
    @ApiModelProperty(value="用戶名",name="name",required=true)
    private String name;

    /**
     *年齡
     */
    private Integer age;

}

UserController

@RestController
@RequestMapping(value = "/user", produces =  MediaType.APPLICATION_JSON_VALUE)
@Api(value = "用戶信息查詢", description = "用戶基本信息操作API", tags = "UserController", consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
public class UserController {

    @ApiOperation(value = "/getUser", notes = "根據姓名查詢用戶信息")
    @RequestMapping(value = "getUser", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    public User getUser(@RequestParam("name") String name){
        User user = new User();
        user.setId("123");
        user.setName(name);
        user.setAge(25);
        return user;
    }

    @ApiOperation(value = "/addUser", notes = "添加一個用戶")
    @RequestMapping(value = "addUser", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    public User addUser(@RequestBody User user){
        return user;
    }

}

關鍵的Test類

@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
@RunWith(SpringRunner.class)
@SpringBootTest
public class Swagger2OfflineApplicationTests {

    private String snippetDir = "target/generated-snippets";
    private String outputDir  = "target/asciidoc";

    @Autowired
    private MockMvc mockMvc;

    @After
    public void Test() throws Exception {
	// 得到swagger.json,寫入outputDir目錄中
	mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))
			.andDo(SwaggerResultHandler.outputDirectory(outputDir).build())
			.andExpect(status().isOk())
			.andReturn();
	// 讀取上一步生成的swagger.json轉成asciiDoc,寫入到outputDir
	// 這個outputDir必須和插件里面<generated></generated>標簽配置一致
	Swagger2MarkupConverter.from(outputDir + "/swagger.json")
		.withPathsGroupedBy(GroupBy.TAGS)// 按tag排序
		.withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式
		.withExamples(snippetDir)
		.build()
		.intoFolder(outputDir);// 輸出
    }

    @Test
    public void Test2() throws Exception{
	User user = new User();
	user.setId("123");
	user.setName("FLY");
	user.setAge(25);
	mockMvc.perform(post("/user/addUser").contentType(MediaType.APPLICATION_JSON)
		.content(JSON.toJSONString(user))
		.accept(MediaType.APPLICATION_JSON))
		.andExpect(status().is2xxSuccessful())
		.andDo(MockMvcRestDocumentation.document("addUser", preprocessResponse(prettyPrint())));
    }

    @Test
    public void TestApi() throws Exception {
        mockMvc.perform(get("/user/getUser").param("name", "FLY")
		.accept(MediaType.APPLICATION_JSON))
		.andExpect(status().isOk())
		.andDo(MockMvcRestDocumentation.document("getUser", preprocessResponse(prettyPrint())));

    }

}

目錄結構以及yml配置

測試

代碼完成后就可啟動項目訪問：http://localhost:9999/swagger-ui.html 這個是在線的文檔顯示。導出離線的需要進入當前項目的根路徑執行命令：mvn clean test

如果接口多的話命令會執行一會。結束后在 target/asciidoc 目錄下會生成兩個文件夾分別是 html 和 pdf 里面就是對應格式的離線文檔了。

如果你的測試用例都寫了而且可以測試通過，這個例子也將會顯示在導出的離線文檔里。

 

獲取源碼地址：https://github.com/moyanxiaoq/boot-demo/tree/master/swagger-offline


免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。



猜您在找 swagger2 導出離線Word/PDF/HTML文檔 swagger導出離線文檔 swagger-ui 導出離線文檔md格式 swagger導出離線接口文檔 使用swagger2markup導出swagger離線PDF/HTML文檔 怎么將swagger API導出為HTML或者PDF 在.Net Core WebAPI下給Swagger增加導出離線文檔功能 將Swagger2文檔導出為HTML或markdown等格式離線閱讀 swagger2 導出api為html和word文檔 API文檔工具——Swagger
 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM