Swagger에서 문자열 배열을 본문 매개 변수로 지정

1. 개요

Swagger는 REST API를 문서화하고 설명하기위한 일련의 사양입니다. 또한 엔드 포인트 매개 변수에 대한 예제 값을 제공합니다.

이 자습서에서는이 동작이 기본적으로 활성화되어 있지 않으므로 String 배열 의 기본 예제 값을 생성하는 방법을 보여줍니다 .

2. Swagger에서 문자열 배열을 본문 매개 변수로 지정

이 문제는 Swagger에서 문자열 배열을 본문 매개 변수로 지정하려고 할 때 발생합니다.

Swagger의 기본 예제 값은 Swagger 편집기에서 볼 수 있듯이 약간 불투명합니다.

그래서, 여기서 우리는 Swagger가 배열 내용이 어떤 모습이어야하는지에 대한 예를 실제로 보여주지 않는다는 것을 알 수 있습니다. 추가하는 방법을 살펴 보겠습니다.

3. YAML

먼저 YAML 표기법을 사용하여 Swagger에서 문자열 배열을 지정하는 것으로 시작합니다. 스키마 섹션에는 type : array with items String을 포함 합니다.

API를 더 잘 문서화하고 사용자에게 지시하기 위해 값을 삽입하는 방법 의 예제 레이블을 사용할 수 있습니다 .

parameters: - in: body description: "" required: true name: name schema: type: array items: type: string example: ["str1", "str2", "str3"]

이제 디스플레이가 어떻게 더 유익한 지 살펴 보겠습니다.

4. Springfox

또는 Springfox를 사용하여 동일한 결과를 얻을 수 있습니다.

@ApiModel@ApiModelProperty 주석이 있는 데이터 모델에서 dataType예제 를 사용해야합니다 .

@ApiModel public class Foo { private long id; @ApiModelProperty(name = "name", dataType = "List", example = "[\"str1\", \"str2\", \"str3\"]") private List name;

그런 다음 Swagger가 데이터 모델을 가리 키도록 컨트롤러 에 주석을 추가해야합니다 .

따라서 @ApiImplicitParams 를 사용 하겠습니다 .

@RequestMapping(method = RequestMethod.POST, value = "/foos") @ResponseStatus(HttpStatus.CREATED) @ResponseBody @ApiImplicitParams({ @ApiImplicitParam(name = "foo", value = "List of strings", paramType = "body", dataType = "Foo") }) public Foo create(@RequestBody final Foo foo) {

그리고 그게 다야!

5. 결론

REST API를 문서화 할 때 문자열 배열 인 매개 변수가있을 수 있습니다. 이상적으로는 예제 값으로이를 문서화합니다.

예제 속성을 사용하여 Swagger에서이를 수행 할 수 있습니다 . 또는 Springfox에서 예제 주석 속성을 사용할 수 있습니다 .

항상 그렇듯이 코드는 GitHub에서 사용할 수 있습니다.