在Spring的RequestBody中使用Swagger给予示例

2 年 ago
清, 宇
1 minute

举个例子，如果在字符串上添加 @RequestBody，并在swagger-ui中引用它，那么界面上的输入示例可能不够友好。

@RestController
public class SampleRestController {
  @PostMapping("/sample")
  public String sample(@RequestBody String body) {
    ...
image.png

因此，我希望默认显示一些适当的示例json等作为参考。

隨意編寫build.gradle。

plugins {
  id 'org.springframework.boot' version '2.7.1'
  id 'io.spring.dependency-management' version '1.0.11.RELEASE'
  id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

configurations {
  compileOnly {
    extendsFrom annotationProcessor
  }
}

repositories {
  mavenCentral()
}

dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-web'
  compileOnly 'org.projectlombok:lombok'
  developmentOnly 'org.springframework.boot:spring-boot-devtools'
  annotationProcessor 'org.projectlombok:lombok'
  testImplementation 'org.springframework.boot:spring-boot-starter-test'
  
  implementation 'org.springdoc:springdoc-openapi-ui:1.6.9'
}

tasks.named('test') {
  useJUnitPlatform()
}

设定的例子如下。由于RequestBody的名称重复，导致描述冗长是一个难点。

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.ExampleObject;

@RestController
public class SampleRestController {

  @PostMapping("/sample")
  public String sample(
      @RequestBody @io.swagger.v3.oas.annotations.parameters.RequestBody(content = @Content(examples = {
          @ExampleObject(name = "sample001", value = "{ \"name\": \"Tanaka\", \"age\": 26 }"),
          @ExampleObject(name = "sample002", value = "{ \"name\": \"Satou\", \"age\": 18 }")
      })) String body) {
    return "asd";
  }
}

在上述的设置中，下面所列的结果如下。

image.png
bannerAds