编写文档

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

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

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

  • maven添加swagger
  1. <!-- swagger2 -->
  2. <dependency>
  3.     <groupId>io.springfox</groupId>
  4.     <artifactId>springfox-swagger2</artifactId>
  5.     <version>2.9.2</version>
  6. </dependency>
  7. <dependency>
  8.     <groupId>com.github.xiaoymin</groupId>
  9.     <artifactId>swagger-bootstrap-ui</artifactId>
  10.     <version>1.9.5</version>
  11. </dependency>
  • 在config中添加swagger配置
  1. @Configuration
  2. public class OpenServiceConfig extends AlipayServiceConfiguration {
  3.     /**
  4.      * 开启文档，本地微服务文档地址：http://localhost:2222/doc.html
  5.      * http://ip:port/v2/api-docs
  6.      */
  7.     @Configuration
  8.     @EnableSwagger2
  9.     public static class Swagger2 extends SwaggerSupport {
  10.         @Override
  11.         protected String getDocTitle() {
  12.             return "故事API";
  13.         }
  14.     }
  15. }

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

  • 编写swagger注解

分别在请求参数和返回结果类中编写@ApiModelProperty

  1. // 请求参数
  2. @Data
  3. public class StoryParam {
  4.     @ApiModelProperty(value = "故事ID", example = "111")
  5.     private int id;
  7.     @ApiModelProperty(value = "故事名称", required = true, example = "白雪公主")
  8.     private String name;
  9. }
  11. // 返回结果
  12. @Data
  13. public class StoryResult {
  14.     @ApiModelProperty(value = "故事ID", example = "1")
  15.     private Long id;
  17.     @ApiModelProperty(value = "故事名称", example = "海底小纵队")
  18.     private String name;
  20.     @ApiModelProperty(value = "创建时间", example = "2019-04-14 19:02:12")
  21.     private Date gmt_create;
  22. }
  • 在接口方法上编写@ApiOperation注解
  1. /**
  2.  * 参数绑定
  3.  *
  4.  * @param story 对应biz_content中的内容，并自动JSR-303校验
  5.  * @return
  6.  */
  7. @ApiOperation(value = "获取故事信息", notes = "说明接口的详细信息，介绍，用途，注意事项等。")
  8. @ApiMapping(value = "alipay.story.find")
  9. public StoryResult getStory2(StoryParam story) {
  10.     log.info("获取故事信息参数, story: {}", story);
  11.     // 获取其它参数
  12.     OpenContext openContext = ServiceContext.getCurrentContext().getOpenContext();
  13.     String app_id = openContext.getAppId();
  14.     StoryResult result = new StoryResult();
  15.     result.setName("白雪公主, app_id:" + app_id);
  16.     result.setGmt_create(new Date());
  17.     return result;
  18. }

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

查看文档

  • 确保注册中心、网关、微服务正常启动
  • 运行WebsiteServerApplication.java
  • 访问http://localhost:8083

效果图如下

预览

注解对应关系

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

预览

预览