Swagger2离线文档：PDF和Html5格式

 

Swagger2在线文档

 

(内容为原网站转发,最后执行的效果.生成了pdf 和html.但是点击pdf/html没有看到文档而是去了csdn首页还望好心人看到这篇文章以后配置成功加以教导)

原网站链接:https://blog.csdn.net/fly910905/article/details/79131755

0.程序结构

 

• 项目源码-Swagger2离线文档：PDF和Html5格式

 

1.Maven配置

3. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

4. xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

5. 4.0.0

6.  

7. com.swagger.offline

8. SwaggerOfflineDoc

9. 1.0-SNAPSHOT

10.  

12. org.springframework.boot

13. spring-boot-starter-parent

14. 1.5.2.RELEASE

16.  

18. ${project.build.directory}/generated-snippets

19.  

20. ${project.basedir}/docs/asciidoc

21. ${project.build.directory}/asciidoc

22. ${project.build.directory}/asciidoc/html

23. ${project.build.directory}/asciidoc/pdf

24.  
26.  
28.  

30. com.alibaba

31. fastjson

32. 1.2.8

34.  

37. org.springframework.boot

38. spring-boot-starter-web

42. org.springframework.boot

43. spring-boot-starter-test

49. io.springfox

50. springfox-swagger2

51. 2.6.1

54. io.springfox

55. springfox-swagger-ui

56. 2.6.1

60. org.springframework.restdocs

61. spring-restdocs-mockmvc

62. 1.1.2.RELEASE

63. test

67. io.springfox

68. springfox-staticdocs

69. 2.6.1

72.  

74. SwaggerOfflineDoc

79. org.apache.maven.plugins

80. maven-surefire-plugin

85. org.asciidoctor

86. asciidoctor-maven-plugin

87. 1.5.3

92. org.asciidoctor

93. asciidoctorj-pdf

94. 1.5.0-alpha.14

98. org.jruby

99. jruby-complete

100. 1.7.21

103.  

107. ${asciidoctor.input.directory}

108. index.adoc

110. book

111. left

112. 3

117. ${generated.asciidoc.directory}

125. output-html

126. test

128. process-asciidoc

131. html5

132. ${asciidoctor.html.output.directory}

137. output-pdf

138. test

140. process-asciidoc

143. pdf

144. ${asciidoctor.pdf.output.directory}

151.  
152.  

 

 

2.index.adoc

• 路径：项目名/docs/asciidoc/index.adoc

1. include::{generated}/overview.adoc[]

2. include::{generated}/definitions.adoc[]

3. include::{generated}/paths.adoc[]

3.Swagger2配置

1. package com.swagger.offline.config;

2.  

3. import org.springframework.context.annotation.Bean;

4. import org.springframework.context.annotation.Configuration;

5. import springfox.documentation.builders.ApiInfoBuilder;

6. import springfox.documentation.builders.PathSelectors;

7. import springfox.documentation.builders.RequestHandlerSelectors;

8. import springfox.documentation.service.ApiInfo;

9. import springfox.documentation.spi.DocumentationType;

10. import springfox.documentation.spring.web.plugins.Docket;

11. import springfox.documentation.swagger2.annotations.EnableSwagger2;

12.  
13.  

14. /**

15. * @version V1.0

16. * @Title: Swagger配置类

17. * @ClassName: com.newcapec.config.swagger.Swagger2Configuration.java

18. * @Description:

19. * @Copyright 2016-2017 - Powered By 研发中心

20. * @author: 王延飞

21. * @date:2017-12-11 8:20

22. */

23.  

24. @Configuration

25. @EnableSwagger2

26. public class SwaggerConfiguration {

27. @Bean

28. public Docket buildDocket() {

29. return new Docket(DocumentationType.SWAGGER_2)

30. .apiInfo(buildApiInfo())

31. .select()

32. //要扫描的API(Controller)基础包

33. .apis(RequestHandlerSelectors.basePackage("com.swagger.offline.controller"))

34. .paths(PathSelectors.any())

35. .build();

36. }

37.  

38. /**

39. * @param

40. * @return springfox.documentation.service.ApiInfo

41. * @Title: 构建API基本信息

42. * @methodName: buildApiInfo

43. * @Description:

44. * @author: 王延飞

45. * @date: 2017-12-11 8:44

46. */

47. private ApiInfo buildApiInfo() {

48.  

49. return new ApiInfoBuilder()

50. .title("用户信息API文档")

51. .description("这里除了查看接口功能外，还提供了调试测试功能")

52. .contact("王延飞")

53. .version("1.0")

54. .build();

55.  

56. }

57. }

 

 

4.实体类

1. import io.swagger.annotations.ApiModel;

2. import io.swagger.annotations.ApiModelProperty;

3.  

4. @ApiModel(value = "User", description = "用户信息描述")

5. public class User {

6. /**

7. * 学号

8. */

9. @ApiModelProperty("证件号")

10. private int id;

11. /**

12. * 姓名

13. */

14. @ApiModelProperty("姓名")

15. private String name;

16. /**

17. * 年龄

18. */

19. @ApiModelProperty("年龄")

20. private int age;

21. /**

22. * 性别

23. */

24. @ApiModelProperty("性别")

25. private String sex;

26. /**

27. * 住址

28. */

29. @ApiModelProperty("家庭住址")

30. private String address;

31. public int getId() {

32. return id;

33. }

34. public void setId(int id) {

35. this.id = id;

36. }

37. public String getName() {

38. return name;

39. }

40. public void setName(String name) {

41. this.name = name;

42. }

43. public int getAge() {

44. return age;

45. }

46. public void setAge(int age) {

47. this.age = age;

48. }

49. public String getSex() {

50. return sex;

51. }

52. public void setSex(String sex) {

53. this.sex = sex;

54. }

55. public String getAddress() {

56. return address;

57. }

58. public void setAddress(String address) {

59. this.address = address;

60. }

61. @Override

62. public String toString() {

63. return "User{" +

64. "id=" + id +

65. ", name='" + name + '\'' +

66. ", age=" + age +

67. ", sex='" + sex + '\'' +

68. ", address='" + address + '\'' +

69. '}';

70. }

71. }

 

5.Controller

 

1. import io.swagger.annotations.Api;

2. import io.swagger.annotations.ApiOperation;

3. import org.springframework.http.MediaType;

4. import org.springframework.stereotype.Controller;

5. import org.springframework.web.bind.annotation.*;

6. /**

7. * @Title:

8. * @ClassName: UserController.java

9. * @Description:

10. *

11. * @Copyright 2016-2018 - Powered By 研发中心

12. * @author: 王延飞

13. * @date: 2018-01-22 16:08

14. * @version V1.0

15. */

16. @Controller

17. @RequestMapping(value = "/user", produces = MediaType.APPLICATION_JSON_VALUE)

18. @Api(value = "用户信息查询", description = "用户基本信息操作API", tags = "UserApi", consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)

19. public class UserController {

20. @ApiOperation(value = "/getUser", notes = "根据姓名查询用户信息")

21. @RequestMapping(value = "getUser", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)

22. @ResponseBody

23. public User getUser(@RequestParam("name") String name){

24. User user = new User();

25. user.setId(123456);

26. user.setName(name);

27. user.setAge(25);

28. user.setAddress("河南郑州");

29. user.setSex("男");

30. return user;

31. }

32. @ApiOperation(value = "/addUser", notes = "添加一个用户")

33. @RequestMapping(value = "addUser", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)

34. @ResponseBody

35. public User addUser(@RequestBody User user){

36. return user;

37. }

38. }

6.测试类

 

1. import com.alibaba.fastjson.JSON;

2. import io.github.robwin.markup.builder.MarkupLanguage;

3. import io.github.robwin.swagger2markup.GroupBy;

4. import io.github.robwin.swagger2markup.Swagger2MarkupConverter;

5. import org.junit.After;

6. import org.junit.Test;

7. import org.junit.runner.RunWith;

8. import org.springframework.beans.factory.annotation.Autowired;

9. import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;

10. import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;

11. import org.springframework.boot.test.context.SpringBootTest;

12. import org.springframework.http.MediaType;

13. import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation;

14. import org.springframework.test.context.junit4.SpringRunner;

15. import org.springframework.test.web.servlet.MockMvc;

16. import springfox.documentation.staticdocs.SwaggerResultHandler;

17. import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;

18. import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.post;

19. import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;

20. import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;

21. import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

22. /**

23. * @Title:

24. * @ClassName: SwaggerStaticDocTest.java

25. * @Description:

26. *

27. * @Copyright 2016-2018 - Powered By 研发中心

28. * @author: 王延飞

29. * @date: 2018-01-22 16:06

30. * @version V1.0

31. */

32. @AutoConfigureMockMvc

33. @AutoConfigureRestDocs(outputDir = "target/generated-snippets")

34. @RunWith(SpringRunner.class)

35. @SpringBootTest

36. public class SwaggerStaticDocTest {

37. private String snippetDir = "target/generated-snippets";

38. private String outputDir = "target/asciidoc";

39. @Autowired

40. private MockMvc mockMvc;

41. @After

42. public void Test() throws Exception {

43. // 得到swagger.json,写入outputDir目录中

44. mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))

45. .andDo(SwaggerResultHandler.outputDirectory(outputDir).build())

46. .andExpect(status().isOk())

47. .andReturn();

48. // 读取上一步生成的swagger.json转成asciiDoc,写入到outputDir

49. // 这个outputDir必须和插件里面标签配置一致

50. Swagger2MarkupConverter.from(outputDir + "/swagger.json")

51. .withPathsGroupedBy(GroupBy.TAGS)// 按tag排序

52. .withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式

53. .withExamples(snippetDir)

54. .build()

55. .intoFolder(outputDir);// 输出

56. }

57. @Test

58. public void TestApi() throws Exception {

59. mockMvc.perform(get("/user/getUser").param("name", "FLY")

60. .accept(MediaType.APPLICATION_JSON))

61. .andExpect(status().isOk())

62. .andDo(MockMvcRestDocumentation.document("getUser", preprocessResponse(prettyPrint())));

63. User user = new User();

64. user.setId(123456);

65. user.setName("FLY");

66. user.setAge(25);

67. user.setAddress("河南郑州");

68. user.setSex("男");

69. mockMvc.perform(post("/user/addUser").contentType(MediaType.APPLICATION_JSON)

70. .content(JSON.toJSONString(user))

71. .accept(MediaType.APPLICATION_JSON))

72. .andExpect(status().is2xxSuccessful())

73. .andDo(MockMvcRestDocumentation.document("addUser", preprocessResponse(prettyPrint())));

74. }

75. }

 

7.测试

 

mvn clean test

生成的PDF和HTML文件：target/asciidoc/html and target/asciidoc/pdf

 

html格式

 

 

pdf格式