SpringBoot 통합 Swagger 2 인 스 턴 스 방법

소프트웨어 개발 을 할 때 인터페이스 문 서 를 쓰 는 것 을 피 할 수 없다.이 문서 들 은 인터페이스의 유형,요청 한 URL,전송 과 반환 값 형식 등 정 보 를 명확 하 게 써 서 전단 과 상호작용 을 하거나 테스트 에 인터페이스 테스트 를 제공 해 야 한다.그러나 손 으로 쓴 문 서 는 한편 으로 는 우리 에 게 많은 업 무량 을 가 져 다 주 었 고,다른 한편 으로 는 인터페이스 가 변경 되면 관련 자 에 게 자주 수정 하고 보 내야 하 며 어느새 업 무량 을 증가 시 켰 다.소 편 은 문 서 를 만 드 는 도구 인 Swagger 를 소개 합 니 다.손 이 간단 하고 학습 원가 가 낮 으 며 SpringBoot 프로젝트 를 개발 하기에 매우 적합 합 니 다.지금 은 소 편 과 함께 공부 하 세 요.
우선 pom 파일 에 swagger 2 의 의존 도 를 추가 해 야 합 니 다.의존 하 는 jar 패 키 지 는 다음 그림 과 같 습 니 다.

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.8.0</version>
</dependency>
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.8.0</version>
</dependency>

Swagger 설정 클래스 Swagger2Config 를 작성 합 니 다.클래스 에@Configuration 과@Enable Swagger 2 주 해 를 추가 하면 설정 클래스 임 을 나타 내 고 Swagger 를 동시에 엽 니 다.아래 의 정 보 는 구체 적 인 상황 에 따라 수정 할 수 있다.

@Bean
public Docket api() {
  return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()
      //            
      .apis(RequestHandlerSelectors.basePackage("com.spring.jpa.user"))
      .paths(PathSelectors.any())
      .build();
}

private ApiInfo apiInfo() {
  return new ApiInfoBuilder()
      .title("swagger-api  ")
      .description("      ")
      //      
      .termsOfServiceUrl("https://baidu.com")
      .version("1.0")
      .contact(new Contact("NWSL", "http://baidu.com", "[email protected]"))
      .build();
}

 

다음은 Controller 층 에 주 해 를 추가 해 야 합 니 다.@Api(value="/test 1",tags="사용자 인터페이스 모듈 테스트"), @Api 라 는 주 해 는 요청 한 클래스 에 사 용 됩 니 다.클래스 에 대한 설명 을 표시 합 니 다.그 중에서 tags="이러한 역할 을 설명 하고 UI 인터페이스 에서 볼 수 있 는 주해",value="이 매개 변 수 는 의미 가 없고 UI 인터페이스 에서 도 볼 수 있 기 때문에 설정 할 필요 가 없습니다."이 주해 의 사용 은 아래 그림 과 같다.

 
다음은 방법 에 주 해 를 추가 해 야 합 니 다.다음 과 같 습 니 다.@Api Operation,@Api ImplicitParams,@Api ImplicitParam 의 역할 은 다음 그림 과 같 습 니 다.@ApiResponses:요청 한 방법 으로@ApiResponse 를 표시 합 니 다.@ApiResponses 에서 잘못된 응답 정 보 를 표현 하 는 데 사 용 됩 니 다.
방법 중의 사용 은 아래 그림 과 같다.

@ApiOperation(value="      ", notes = "      ")
@ApiImplicitParams({
    @ApiImplicitParam(name = "name", value = "    ", required = true, dataType = "String",paramType = "query"),
    @ApiImplicitParam(name = "age", value = "    ", required = true,paramType = "query")
})

Integer 형식 이 라면 dataType="Integer"는 생략 할 수 있 습 니 다.오히려 생 성 된 문서 호출 에 오류 가 발생 했 습 니 다.



다음은 실체 류 매개 변 수 를 전달 하 는 주 해 를 어떻게 쓰 는 지 소개 합 니 다.@ApiModel,@ApiModelproperty 에 사용 해 야 합 니 다.구체 적 인 용법 은 다음 그림 과 같 습 니 다.매개 변 수 를 받 는 실체 류 에 우 리 는 다음 그림 과 같이 이 두 개의 주 해 를 추가 해 야 한다.


인터페이스 에 주 해 를 다 쓴 후에 저 희 는 서 비 스 를 시작 한 다음 에 swagger 의 UI 페이지 를 엽 니 다.8091 포트 는 제 컴퓨터 서비스 가 시작 하 는 포트 입 니 다.요청 한 주 소 는 다음 그림 과 같 습 니 다.모든 컨트롤 러 클래스 가 문 서 를 만 드 는 것 을 볼 수 있 습 니 다.UserController 는 클래스 의 설명 을 추 가 했 습 니 다.

다음은 UserController 의 인 터 페 이 스 를 테스트 합 니 다.아래 그림 에서 보 듯 이 UserController 의 모든 인터페이스 문 서 를 생 성 했 습 니 다.먼저 사용자 인 터 페 이 스 를 추가 합 니 다.아래 그림 에서 보 듯 이 왜 Integer 형식의 age 필드 는 생 성 된 인터페이스 문서 에서 매개 변수 유형 이 ref 로 변 했 습 니까?앞에서 언급 한 바 와 같이 주 해 를 쓸 때 dataType="Integer"는 생략 해 야 합 니 다.그렇지 않 으 면 이 문제 가 발생 할 수 있 습 니 다.정확 한 것 은 다음 과 같 습 니 다.age 가 Integer 유형 임 을 볼 수 있 습 니 다.



인터페이스 오른쪽 에 Try it out 이 있 는 것 을 볼 수 있 습 니 다.이 단 추 를 누 르 면 호출 페이지 에 들 어 갑 니 다.다음 페이지 에 파 라 메 터 를 작성 한 후에 Execute 를 실행 하면 됩 니까?아니면 age 파라미터 ref 의 문 제 를 실행 하면 오류 가 발생 할 수 있 습 니 다.주석 에 있 는 Integer 형식 을 제거 하고 실행 하면 됩 니 다.


다음은 Get 요청 을 보 겠 습 니 다.이 요청 은 전 참 없 이 바로 실행 하면 됩 니 다.결 과 는 다음 그림 과 같 습 니 다.우 리 는 Swagger 가 생 성 한 restful 형식의 인터페이스 문 서 를 볼 수 있어 서 디 버 깅 하기에 매우 편리 하 다.


다음은 update 의 인 터 페 이 스 를 실행 합 니 다.이것 은 위 에서 실체 류 로 인 자 를 받 는 방법 입 니 다.매개 변수의 예 를 볼 수 있 습 니 다.우 리 는 매개 변 수 를 수정 한 후에 실행 하면 됩 니 다.이상 swagger 2 와 springboot 이 통합 되 었 습 니 다.