java - 使用 Swagger 将创建的日期时间添加到 REST API

Question

我有几个 API 并使用 springfox-swagger 来获取 API 文档。 我需要将创建日期添加到相应的 API。我如何使用 swagger 实现此目的。我不需要任何 API 版本控制。

例如:

@ApiOperation(value = "Creates a new user and returns the created user.")
    @PostMapping(/user)
    public ResponseEntity<UserDto> createUser(@RequestBody UserDto userDto) {
        User user =userService.create(userDto);
        return new ResponseEntity<>(UserMappers.USER_ENTITY_TO_DTO.apply(user),HttpStatus.CREATED);
    }

在上面的例子中，我想添加/user的创建日期，这样我就可以追溯创建日期。

Answer 1

在我的项目中，我有类似的需求。作为解决方案，我创建了一个自定义注释(用于标记端点)并编写了一个插件(用于更新 API 描述)。

选项#1

• @ApiSince注解:

  @Target(ElementType.METHOD)
  @Retention(RetentionPolicy.RUNTIME)
  public @interface ApiSince {
      String value() default "";
  }
  

• ApiSincePlugin 插件:

  @Component
  public class ApiSincePlugin implements OperationBuilderPlugin {
  
      private final DescriptionResolver resolver;
  
      @Autowired
      public ApiSincePlugin(DescriptionResolver resolver) {
          this.resolver = resolver;
      }
  
      @Override
      public void apply(OperationContext context) {
  
          final String sinceTemplate = "### Since %s%n%n%s";
          String notes = "";
          Optional<ApiOperation> apiOperationOptional = context.findAnnotation(ApiOperation.class);
          if (apiOperationOptional.isPresent()) {
              notes = apiOperationOptional.get().notes();
          }
          String finalNotes = notes;
          Optional<ApiSince> apiSinceOptional = context.findAnnotation(ApiSince.class);
          if (apiSinceOptional.isPresent()) {
              finalNotes = String.format(sinceTemplate, apiSinceOptional.get().value(), notes);
          }
          context.operationBuilder().notes(resolver.resolve(finalNotes));
      }
  
      @Override
      public boolean supports(DocumentationType type) {
          return true;
      }
  }
  

• @ApiSince 实际操作:

  @ApiSince(value = "2019-10-31")
  @PostMapping(value = "/login")
  @ApiOperation(value = "Authenticate user", nickname = "login", notes = "your API description")
  @ResponseStatus(HttpStatus.OK)
  @ApiResponses(value = {
      @ApiResponse(code = 200, response = LoginResponse.class, message = HTTP_200_OK),
      ...
  })
  @ResponseBody
  ResponseEntity<LoginResponse> login(...);
  

  

---

如果您不想在描述中添加它，而是将其作为额外的 JSON 属性，请查看此解决方案:Custom Operation Builder Plugin .

选项 #2

• @ApiSince 注解(代码同上)

• ApiSincePlugin 插件:

  @Component
  public class ApiSincePlugin implements OperationBuilderPlugin {
  
      @Override
      public void apply(OperationContext context) {
          Optional<ApiSince> annotation = context.findAnnotation(ApiSince.class);
          if (annotation.isPresent()) {
              String value = annotation.get().value();
              ObjectVendorExtension extention = new ObjectVendorExtension("x-since");
              extention.addProperty(new StringVendorExtension("value", value));
              context.operationBuilder().extensions(Collections.singletonList(extention));
          }
      }
  
      @Override
      public boolean supports(DocumentationType documentationType) {
          return true;
      }
  }
  

• 在 Swagger UI 中激活扩展:

  @Bean
  UiConfiguration uiConfig() {
      return UiConfigurationBuilder
              .builder()
              .showExtensions(true)
              ...
              .build();
  }
  

• @ApiSince 实际操作(代码同上):