[关闭]
@javazjm 2017-10-30T10:42:35.000000Z 字数 8390 阅读 2683

SpringBoot系列学习十二：API文档生成

Springboot swagger JApiDocs

swagger

官网

1. 在线文档

1.1 引入依赖

  1. <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
  2. <dependency>
  3.     <groupId>io.springfox</groupId>
  4.     <artifactId>springfox-swagger2</artifactId>
  5.     <version>2.7.0</version>
  6. </dependency>
  8. <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
  9. <dependency>
  10.     <groupId>io.springfox</groupId>
  11.     <artifactId>springfox-swagger-ui</artifactId>
  12.     <version>2.7.0</version>
  13. </dependency>

1.2 创建Swagger2配置类

在Application.java同级创建Swagger2的配置类

  1. @Configuration // 让Spring来加载该类配置
  2. @EnableSwagger2 // 启用Swagger2
  3. public class Swagger2Config {
  5.     /**
  6.      * 通用配置 生成离线文档不可缺
  7.      * @return
  8.      */
  9.     @Bean
  10.     public Docket configSpringfoxDocket_all() {
  11.         return new Docket(DocumentationType.SWAGGER_2)
  12.                 .produces(Sets.newHashSet("application/json"))
  13.                 .consumes(Sets.newHashSet("application/json"))
  14.                 .protocols(Sets.newHashSet("http", "https"))
  15.                 .apiInfo(apiInfo())
  16.                 .forCodeGeneration(true)
  17.                 .select()
  18.                 .paths(regex("/api.*"))
  19.                 .build();
  20.     }
  22.     /**
  23.      * 针对user的配置
  24.      * @return
  25.      */
  26.     @Bean
  27.     public Docket createUserRestApi() {
  28.         return new Docket(DocumentationType.SWAGGER_2)
  29.                 .groupName("user")
  30.                 .produces(Sets.newHashSet("application/json"))
  31.                 .consumes(Sets.newHashSet("application/json"))
  32.                 .protocols(Sets.newHashSet("http", "https"))
  33.                 .apiInfo(apiInfo())
  34.                 .select()
  35.                 .apis(RequestHandlerSelectors.basePackage("com.jimzhang.web")) //扫描指定包下的Controller,并生成文档 （除了被@ApiIgnore指定的请求）
  36.                 .paths(regex("/api/users.*"))
  37. //                .paths(PathSelectors.any())
  38.                 .build();
  39.     }
  41.     /**
  42.      * 创建基本信息，会展示在文档首页
  43.      * @return
  44.      */
  45.     private ApiInfo apiInfo(){
  46.         return new ApiInfoBuilder()
  47.                 .title("Spring Boot中使用Swagger2构建RESTful APIs")
  48.                 .description("欢迎关注我的博客：http://www.jianshu.com/u/450bfbaff4e3")
  49.                 .termsOfServiceUrl("http://www.jianshu.com/u/450bfbaff4e3")
  50.                 .contact(new Contact("Spring官网 ", "https://spring.io/projects", "1539745948@qq.com"))
  51.                 .version("1.0").build();
  52.     }
  53. }

1.3 添加文档内容

  1. @Api(tags = "用户操作")
  2. @RestController
  3. @RequestMapping(value="/users")     // 通过这里配置使下面的映射都在/users下，可去除
  4. public class UserController {
  6.     static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());
  8.     @ApiOperation(value="获取用户列表", notes="")
  9.     @RequestMapping(value={""}, method= RequestMethod.GET)
  10.     public List<User> getUserList() {
  11.         List<User> r = new ArrayList<User>(users.values());
  12.         return r;
  13.     }
  15.     @ApiOperation(value="创建用户", notes="根据User对象创建用户")
  16.     @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
  17.     @RequestMapping(value="", method= RequestMethod.POST)
  18.     public String postUser(@RequestBody User user) {
  19.         users.put(user.getId(), user);
  20.         return "success";
  21.     }
  23.     @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
  24.     @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
  25.     @RequestMapping(value="/{id}", method= RequestMethod.GET)
  26.     public User getUser(@PathVariable Long id) {
  27.         return users.get(id);
  28.     }
  30.     @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
  31.     @ApiImplicitParams({
  32.             @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
  33.             @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
  34.     })
  35.     @RequestMapping(value="/{id}", method= RequestMethod.PUT)
  36.     public String putUser(@PathVariable Long id, @RequestBody User user) {
  37.         User u = users.get(id);
  38.         u.setName(user.getName());
  39.         u.setAge(user.getAge());
  40.         users.put(id, u);
  41.         return "success";
  42.     }
  44.     @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
  45.     @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
  46.     @RequestMapping(value="/{id}", method= RequestMethod.DELETE)
  47.     public String deleteUser(@PathVariable Long id) {
  48.         users.remove(id);
  49.         return "success";
  50.     }
  52. }

1.4 访问

http://localhost:8080/swagger-ui.html

API注解说明

  1. swagger2使用说明：
  2.     @Api：用在类上，说明该类的作用
  3.     @ApiOperation：用在方法上，说明方法的作用
  4.     @ApiIgnore：使用该注解忽略这个API
  5.     @ApiImplicitParams：用在方法上包含一组参数说明
  6.     @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
  7.         paramType：参数放在哪个地方
  8.         header-->请求参数的获取：@RequestHeader
  9.         query-->请求参数的获取：@RequestParam
  10.         path（用于restful接口）-->请求参数的获取：@PathVariable
  11.         body（不常用）
  12.         form（不常用）
  13.         name：参数名
  14.         dataType：参数类型
  15.         required：参数是否必须传
  16.         value：参数的意思
  17.         defaultValue：参数的默认值
  18.     @ApiResponses：用于表示一组响应
  19.     @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
  20.         code：数字，例如400
  21.         message：信息，例如"请求参数没填好"
  22.         response：抛出异常的类
  23.     @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
  24.     @ApiModelProperty：描述一个model的属性

2. 离线文档

2.1 引入依赖

  1. <!-- 离线文档依赖 -->
  2. <dependency>
  3.     <groupId>org.springframework.restdocs</groupId>
  4.     <artifactId>spring-restdocs-mockmvc</artifactId>
  5.     <version>1.1.2.RELEASE</version>
  6.     <scope>test</scope>
  7. </dependency>
  8. <dependency>
  9.     <groupId>io.springfox</groupId>
  10.     <artifactId>springfox-staticdocs</artifactId>
  11.     <version>2.6.1</version>
  12. </dependency>

2.2 Maven插件

asciidoctor-maven-plugin插件是用来把Asciidoc格式转成HTML5格式

  1. <build>
  2.     <plugins>
  3.         <plugin>
  4.             <groupId>org.springframework.boot</groupId>
  5.             <artifactId>spring-boot-maven-plugin</artifactId>
  6.         </plugin>
  7.         <!--Asciidoctor Maven 插件是一种官方支持的方式，它可以在 Apache Maven 构建过程中使用 Asciidoctor 转化你的 AsciiDoc 文档。-->
  8.         <!--https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/master/README_zh-CN.adoc-->
  9.         <plugin>
  10.             <groupId>org.asciidoctor</groupId>
  11.             <artifactId>asciidoctor-maven-plugin</artifactId>
  12.             <configuration>
  13.                 <!--配置index.adoc的获取路径-->
  14.                 <!--<sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>-->
  15. 				<outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
  16.                 <sourceDocumentName>index.adoc</sourceDocumentName>
  17.                 <attributes>
  18.                     <doctype>book</doctype>
  19.                     <toc>left</toc>
  20.                     <toclevels>3</toclevels>
  21.                     <generated>${generated.asciidoc.directory}</generated>
  22. 				</attributes>
  23. 			</configuration>
  24. 			<executions>
  25. 				<execution>
  26. 					<id>output-html</id>
  27. 					<phase>test</phase>
  28. 					<goals>
  29. 						<goal>process-asciidoc</goal>
  30. 					</goals>
  31. 					<configuration>
  32. 						<backend>html</backend>
  33. 						<attributes>
  34. 							<snippets>${project.build.directory}/generated-snippets</snippets>
  35.                         </attributes>
  36.                     </configuration>
  37.                 </execution>
  38.             </executions>
  39.         </plugin>
  40.     </plugins>
  41. </build>

2.3 配置文件

在Swagger2Config类中新增入下配置：

  1. /**
  2.  * 通用配置 生成离线文档不可缺
  3.  * @return
  4.  */
  5. @Bean
  6. public Docket configSpringfoxDocket_all() {
  7.     return new Docket(DocumentationType.SWAGGER_2)
  8.             .produces(Sets.newHashSet("application/json"))
  9.             .consumes(Sets.newHashSet("application/json"))
  10.             .protocols(Sets.newHashSet("http", "https"))
  11.             .apiInfo(apiInfo())
  12.             .forCodeGeneration(true)
  13.             .select()
  14.             .paths(regex("/api.*"))
  15.             .build();
  16. }

2.4 添加单元测试文件

  1. @AutoConfigureMockMvc
  2. @AutoConfigureRestDocs(outputDir = "target/generated-snippets")
  3. @RunWith(SpringRunner.class)
  4. @SpringBootTest
  5. public class DocumentationBuild {
  7.     private String snippetDir = "target/asciidoc/generated-snippets";
  8.     private String outputDir = "target/asciidoc";
  10.     @Autowired
  11.     private MockMvc mockMvc;
  13.     @After
  14.     public void Test() throws Exception {
  15.         // 得到swagger.json,写入outputDir目录中
  16.         mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))
  17.                 .andDo(SwaggerResultHandler.outputDirectory(outputDir).build())
  18.                 .andExpect(status().isOk())
  19.                 .andReturn();
  21.         // 读取上一步生成的swagger.json转成asciiDoc,写入到outputDir
  22.         // 这个outputDir必须和插件里面<generated></generated>标签配置一致
  23.         Swagger2MarkupConverter.from(outputDir + "/swagger.json")
  24.                 .withPathsGroupedBy(GroupBy.TAGS)// 按tag排序
  25.                 .withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式
  26.                 .withExamples(snippetDir)
  27.                 .build()
  28.                 .intoFolder(outputDir);// 输出
  29.     }
  32.     @Test
  33.     public void TestApi() throws Exception {
  34.         mockMvc.perform(get("/api/users/1")
  35.                 .accept(MediaType.APPLICATION_JSON))
  36.                 .andExpect(status().isOk())
  37.                 .andDo(MockMvcRestDocumentation.document("查询用户", preprocessResponse(prettyPrint())));  // '查询用户'  名字要与index.adoc 中的一致，否则 生成的文档有误
  39.         User userInfo = new User();
  40.         userInfo.setId(1L);
  41.         userInfo.setName("lisi");
  42.         userInfo.setAge(23);
  43.         mockMvc.perform(post("/api/users").contentType(MediaType.APPLICATION_JSON)
  44.                 .content(JSON.toJSONString(userInfo))
  45.                 .accept(MediaType.APPLICATION_JSON))
  46.                 .andExpect(status().is2xxSuccessful())
  47.                 .andDo(MockMvcRestDocumentation.document("创建用户", preprocessResponse(prettyPrint())));
  50.         mockMvc.perform(get("/api/users")
  51.                 .accept(MediaType.APPLICATION_JSON))
  52.                 .andExpect(status().isOk())
  53.                 .andDo(MockMvcRestDocumentation.document("获取用户列表", preprocessResponse(prettyPrint())));
  56.         User user = new User();
  57.         user.setId(1L);
  58.         user.setName("张晋苗");
  59.         user.setAge(27);
  60.         mockMvc.perform(post("/api/users/1").contentType(MediaType.APPLICATION_JSON)
  61.                 .content(JSON.toJSONString(userInfo))
  62.                 .accept(MediaType.APPLICATION_JSON))
  63.                 .andExpect(status().is2xxSuccessful())
  64.                 .andDo(MockMvcRestDocumentation.document("更新用户详细信息", preprocessResponse(prettyPrint())));
  67.         mockMvc.perform(post("/api/users/delete/1")
  68.                 .accept(MediaType.APPLICATION_JSON))
  69.                 .andExpect(status().isOk())
  70.                 .andDo(MockMvcRestDocumentation.document("删除用户", preprocessResponse(prettyPrint())));
  71.     }
  74. }

2.5 运行

运行单元测试文件，会生成*.adoc和swagger.json文档，均不为空
然后进行打包，在target/asciidoc/html 会生成index.html 就是API文档

直接查看index.html即可。

JApiDocs

github地址：https://github.com/YeDaxia/JApiDocs

参考：
didi
小柒
https://my.oschina.net/dlam/blog/808315

离线文档：

添加新批注
在作者公开此批注前，只有你和作者可见。
回复批注