1. 개요
Swagger 는 REST API를 문서화하고 설명하는 일련의 사양입니다. 또한 Endpoints 매개 변수에 대한 예제 값을 제공합니다.
이 사용방법(예제)에서는 문자열 배열에 대한 기본 예제 값을 생성하는 방법을 보여줍니다. 이 동작은 기본적으로 활성화되어 있지 않기 때문입니다.
2. Swagger에서 본문 매개변수로 문자열 배열 지정
Swagger에서 문자열 배열을 본문 매개변수로 지정하려고 할 때 문제가 발생합니다.
Swagger의 기본 예제 값은 Swagger 편집기 에서 볼 수 있듯이 약간 불투명 합니다 .
그래서 여기서 우리는 Swagger가 배열 내용이 어떻게 보여야 하는지에 대한 예를 실제로 보여주지 않는다는 것을 알 수 있습니다. 추가하는 방법을 살펴보겠습니다.
3. YAML
먼저 YAML 표기법을 사용하여 Swagger에서 문자열 배열을 지정하는 것으로 시작합니다. 스키마 섹션에는 String 항목 이 포함된 type: array 가 포함됩니다 .
API를 더 잘 문서화하고 사용자에게 지시하기 위해 값을 삽입하는 방법에 대한 예제 레이블을 사용할 수 있습니다.
parameters:
- in: body
description: ""
required: true
name: name
schema:
type: array
items:
type: string
example: ["str1", "str2", "str3"]이제 디스플레이가 어떻게 더 많은 정보를 제공하는지 살펴보겠습니다.
4. 스프링폭스
또는 Springfox 를 사용하여 동일한 결과를 얻을 수 있습니다 .
@ApiModel 및 @ApiModelProperty 어노테이션 이 있는 데이터 모델 의 dataType 및 예제 를 사용해야 합니다 .
@ApiModel
public class Foo {
private long id;
@ApiModelProperty(name = "name", dataType = "List", example = "[\"str1\", \"str2\", \"str3\"]")
private List<String> 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에서 사용할 수 있습니다 .
