编写文档

作为开放平台，必须要提供API文档。

SOP采用微服务架构实现，因此文档应该由各个微服务各自实现。难点就是如何统一归纳各个微服务端提供的文档信息，并且统一展示。

写完接口后使用swagger注解来定义自己的文档信息。步骤如下：

  • maven添加swagger
  1. <dependency>
  2.     <groupId>io.springfox</groupId>
  3.     <artifactId>springfox-swagger2</artifactId>
  4.     <version>2.9.2</version>
  5.     <exclusions>
  6.         <exclusion>
  7.             <groupId>io.swagger</groupId>
  8.             <artifactId>swagger-models</artifactId>
  9.         </exclusion>
  10.     </exclusions>
  11. </dependency>
  12. <dependency>
  13.     <groupId>io.swagger</groupId>
  14.     <artifactId>swagger-models</artifactId>
  15.     <version>1.5.21</version>
  16. </dependency>
  17. <dependency>
  18.     <groupId>io.springfox</groupId>
  19.     <artifactId>springfox-swagger-ui</artifactId>
  20.     <version>2.9.2</version>
  21. </dependency>
  • 在config中添加swagger配置
  1. @Configuration
  2. public class OpenServiceConfig extends AlipayServiceConfiguration {
  3.     // 开启文档
  4.     @Configuration
  5.     @EnableSwagger2
  6.     public static class Swagger2 extends SwaggerSupport {
  7.         @Override
  8.         protected String getDocTitle() {
  9.             // 不能重复。比如订单服务返回：`订单API`；库存服务返回：`库存API`
  10.             return "图书API";
  11.         }
  12.     }
  13. }

其中getDocTitle()返回文档模块名，不能和其它微服务重复。比如订单服务返回：订单API；库存服务返回：库存API

  • 编写swagger注解
    分别在请求参数和返回结果类中编写@ApiModelProperty
  1. // 请求参数
  2. @Data
  3. public class BookParam {
  4.     @ApiModelProperty(value = "图书id", example = "1")
  5.     private int id;
  7.     @ApiModelProperty(value = "图书ISBN", example = "xxxx")
  8.     private String isbn;
  9. }
  11. // 返回结果
  12. @Data
  13. public class BookVO {
  14.     @ApiModelProperty(value = "图书id", example = "1")
  15.     private int id;
  17.     @ApiModelProperty(value = "图书名称", example = "白雪公主")
  18.     private String name;
  20.     @ApiModelProperty(value = "isbn", example = "xxxxxx")
  21.     private String isbn;
  22. }
  • 在接口方法上编写@ApiOperation注解
  1. @ApiOperation(value="查询书本信息", notes = "可以根据ISBN查询书本信息")
  2. @ApiMapping(value = "book.search")
  3. public BookVO searchBook(BookParam param) {
  4.     BookVO bookVO = new BookVO();
  5.     bookVO.setId(1);
  6.     bookVO.setName("白雪公主，ISBN:" + param.getIsbn());
  7.     bookVO.setIsbn("ABCSSSSDDD");
  8.     return bookVO;
  9. }

其中value属性填接口名称，简明扼要。notes填写接口的详细信息，介绍，用途，注意事项等。

查看文档

  • 启动website-server(运行WebsiteServerApplication.java)
  • 找到sop-website/website-front/pages/doc/doc.html，IDEA下右键—Debug
    如果没有IDEA可以下个webstorm，同样有本地静态服务器功能。

效果图如下

预览

注解对应关系

swagger注解和文档界面显示关系如下图所示：

预览

预览