项目工具三：Swagger导出离线版HTML5和PDF格式api文档

还在那 發表於 2020-1-21 14:25:00

项目工具三：Swagger导出离线版HTML5和PDF格式api文档

<p>之前的文章讲解了swagger2注解的用法以及实例演示，本篇文章介绍一下如何使用swagger2导出离线版的api文档，分为两种格式一个是HTML5一个是PDF。对象属性、接口说明、测试用例都可以导出来方便开发人员很清楚的了解接口！</p>
<h2>相关版本</h2>
<ol class="list-paddingleft-2">
<li>
<p>Springboot版本：1.5.10.RELEASE</p>
</li>
<li>
<p>swagger2版本：2.6.1</p>
</li>
<li>
<p>maven版本：3.2.5</p>
</li>
<li>
<p>JDK版本：8</p>
</li>
<li>
<p>IDEA版本：2017.2.6<br>大家自己测试的时候如果不成功尽量和我版本保持一致。</p>

</li>

</ol>
<h2>index.adoc配置</h2>
<p> </p>
<p><img src="https://img2018.cnblogs.com/common/1505525/202001/1505525-20200121142138453-1397566250.png"></p>
<pre><code>include::{generated}/overview.adoc[]
include::{generated}/definitions.adoc[]
include::{generated}/paths.adoc[]</code></pre>
<h2>pom.xml配置</h2>
<p>pom里面不比之前需要多配置一些东西，这个是大家需要注意的。</p>
<p>properties配置：</p>
<pre><code><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></code></pre>
<p>dependencies依赖配置：</p>
<pre><code><dependencies>

   
   <dependency>
<groupId>com.alibaba</groupId>
<artifactId>fastjson</artifactId>
<version>1.2.46</version>
   </dependency>

   
   <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>

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

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

   
   <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>

   
   <dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.16.20</version>
   </dependency>

</dependencies></code></pre>
<p>plugins插件配置：</p>
<pre><code><build>
   <plugins>


<plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-surefire-plugin</artifactId>
</plugin>

<plugin>
   <groupId>org.asciidoctor</groupId>
   <artifactId>asciidoctor-maven-plugin</artifactId>
   <version>1.5.3</version>
   
   <dependencies>
<dependency>
   <groupId>org.asciidoctor</groupId>
   <artifactId>asciidoctorj-pdf</artifactId>
   <version>1.5.0-alpha.14</version>
</dependency>
       
       <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>
       
       <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>
       
       <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></code></pre>
<h2>Swagger2Config配置类</h2>
<pre><code>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();
   }
}</code></pre>
<h2>User实体类</h2>
<pre><code>@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;

}</code></pre>
<h2>UserController</h2>
<pre><code>@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;
   }<br>
   @ApiOperation(value = "/addUser", notes = "添加一个用户")
   @RequestMapping(value = "addUser", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)
   @ResponseBody
   public User addUser(@RequestBody User user){
       return user;
   }

}</code></pre>
<h2>关键的Test类</h2>
<pre><code>@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
@RunWith(SpringRunner.class)
@SpringBootTest
public class Swagger2OfflineApplicationTests {

   private String snippetDir = "target/generated-snippets";
   private String outputDir  = "target/asciidoc";<br>
   @Autowired
   private MockMvc mockMvc;<br>
   @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())));

   }

}</code></pre>
<h2>目录结构以及yml配置</h2>
<p><img src="https://img2018.cnblogs.com/common/1505525/202001/1505525-20200121142324069-1083383511.png"></p>
<h2>测试</h2>
<p>代码完成后就可启动项目访问：http://localhost:9999/swagger-ui.html 这个是在线的文档显示。导出离线的需要进入当前项目的根路径执行命令：<code>mvn clean test</code></p>
<p><img src="https://img2018.cnblogs.com/common/1505525/202001/1505525-20200121142335593-1091677741.png"></p>
<p>如果接口多的话命令会执行一会。结束后在 <code>target/asciidoc</code> 目录下会生成两个文件夹分别是 <code>html</code> 和 <code>pdf</code> 里面就是对应格式的离线文档了。</p>
<p><img src="https://img2018.cnblogs.com/common/1505525/202001/1505525-20200121142351728-1461546836.png"></p>
<p>如果你的测试用例都写了而且可以测试通过，这个例子也将会显示在导出的离线文档里。</p>
<p><img src="https://img2018.cnblogs.com/common/1505525/202001/1505525-20200121142408799-1262594854.png"></p>
<p><img src="https://img2018.cnblogs.com/common/1505525/202001/1505525-20200121142423663-1980479807.png"></p>
<p> </p>
<p><strong>获取源码地址：</strong>https://github.com/moyanxiaoq/boot-demo/tree/master/swagger-offline</p><br><br>
来源：https://www.cnblogs.com/breka/p/12221614.html

頁: [1]

琼殿技术论坛's Archiver

项目工具三：Swagger导出离线版HTML5和PDF格式api文档