SpringBoot 통합 Swagger api 문서 구축 작업

최근 프로젝트 를 할 때 API 라 는 것 을 사용 해 왔 습 니 다.contrller 주 해 는 제 가 쓸 수 있 습 니 다.이것 도 사용 할 수 있 습 니 다.하지만 저 는 이 물건 이 무엇 인지 모 르 고 신기 합 니 다.관건 은 나 를 한 번 더 함정 에 빠 뜨 렸 다.그의 주 해 는 코드 의 운행 에 영향 을 주 고 주해 의 역할 만 하 는 것 이 아니다.그래서 연구 해 봤 는데
Swagger 는 무엇 입 니까:THE WORLD'S MOST POPULAR API TOOLING
홈 페이지 에 따 르 면
Swagger Inspector:API 테스트 와 OpenAPI 생 성 을 위 한 개발 도구 입 니 다.Swagger Inspector 의 구축 은 개발 자의 세 가지 주요 목 표를 해결 하기 위 한 것 입 니 다.
1.간단 한 API 테스트 수행
2.OpenAPI 문서 생 성
3.새로운 API 기능 탐색
Swagger 는 RESTful 스타일 의 웹 서 비 스 를 생 성,설명,호출,시각 화 하 는 규범 적 이 고 완전한 프레임 워 크 라 는 것 을 이해 합 니 다.쉽게 말 하면 Swagger 는 기능 이 강 한 인터페이스 관리 도구 이 고 다양한 프로 그래 밍 언어의 앞 뒤 분리 솔 루 션 을 제공 합 니 다.제 사용 에 따 르 면 물론 저 는 가장 간단 한 사용 일 뿐 입 니 다.저 는 Swagger 가 다음 과 같은 몇 가지 장점 이 있다 고 생각 합 니 다.
1.Swagger 는 코드 에 통합 하여 개발 할 때 주석 을 통 해 주석 을 작성 하고 API 문 서 를 자동 으로 생 성 할 수 있 습 니 다.
2.프론트 백 엔 드 를 분리 하여 지나치게 의존 하지 않 습 니 다.
3.화면 이 뚜렷 하고 editor 의 실시 간 전시 든 ui 의 전시 든 모두 인성 화 되 어 있 습 니 다.만약 에 자신 이 markdown 으로 만 작성 하면 어떻게 표현 해 야 할 지 고민 하고 고 통 스 럽 습 니 다.
다음 두 가 지 를 나 는 아직 실천 하지 않 았 다.
1.JSon 과 Yml 를 지원 하여 API 문 서 를 작성 하고 json,Yml,markdown 등 형식 으로 내 보 낼 수 있 습 니 다.
2.API 를 작성 하면 해당 SDK 를 자동 으로 생 성 할 수 있 습 니 다.맞습니다.API 인터페이스 코드 가 아직 쓰기 시작 하지 않 았 을 수도 있 습 니 다.해당 SDK 를 만 들 수 있 고 거의 모든 주류 프로 그래 밍 언어 를 지원 하 는 SDK 를 만 들 수 있 습 니 다.
SpringBoot,Maven SwaggerAPI 문서 구축
첫 번 째 단계:SpringBoot 웹 프로젝트 만 들 기
여기 서 소 개 를 많이 할 뿐 발생 할 수 있 는 문제 만 말씀 드 리 겠 습 니 다.프로젝트 를 만 든 후에 디 렉 터 리 구조 가 잘못 되 었 고 src/main/resources 폴 더 만 있 습 니 다.아래 그림 에서 보 듯 이

이때 JDK 버 전 을 설치 한 버 전 으로 업그레이드 하면 다른 폴 더 가 나타 납 니 다.

두 번 째 단계:클래스 생 성 및 pom.xml 설정
1:pom.xml 설정,의존 패키지 추가:
첫 번 째 는 API 가 가 져 온 가방 이 고,두 번 째 는 공식 적 으로 제 시 된 ui 인터페이스 입 니 다.3 과 4 는 spring boot 에 필요 한 jar 가방 입 니 다.

  <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
  </dependency>

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

  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>

  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
  </dependency>

2:Swagger 설정,SwaggerConfig.java 클래스 만 들 기

@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .select()
      .apis(RequestHandlerSelectors.basePackage("com"))
      .paths(PathSelectors.any()).build();
}


private ApiInfo apiInfo() {
  return new ApiInfoBuilder()
    .title("Spring Boot   Swagger2  RESTful APIs")
    .description("myapp")
    .termsOfServiceUrl("http://blog.csdn.net/java_yes")
    .version("1.0").build();
  }
}

여기 특별히 주의해 야 할 점 이 있 습 니 다.
RequestHandler Selectors.basePackage("com.swagger"),주 해 를 스 캔 하 는 설정,즉 API 인터페이스 위치 입 니 다.문장 은 마지막 에 내 가 총 결 할 것 이다.
3:SpringBoot 시작 클래스 만 들 기

@SpringBootApplication
public class Application {
  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }
}

4:controller 생 성
여기 서 controller 두 개 를 만 들 었 습 니 다.@RequestMapping()을 설명 하기 위해 서 입 니 다.이 두 컨트롤 러 는 실제 적 인 의미 가 없어 서 마음대로 만 들 수 있 습 니 다.저 는 단지 SwaggerAPI 를 테스트 하기 위해 서 입 니 다.
GreetingController

@RestController
@RequestMapping(value = "/test")
public class GreetingController {
  private static final String template = "Hello, %s!";
  private final AtomicLong counter = new AtomicLong();

  @RequestMapping(value = "/swagger")
  //@RequestMapping("/swagger")
  //@RequestMapping(value = "/swagger",method = RequestMethod.POST)
  public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
    return new Greeting(counter.incrementAndGet(), String.format(template, name));
  }
}

BookController

@RestController
@Api(tags = "BookController", description = "BookController |       swagger")
@RequestMapping(value = "/books")
public class BookController {

  Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>());

  @ApiOperation(value="    ", notes="    ")
  @ApiImplicitParam(name = "book", value = "      ", required = true, dataType = "Book")
  @RequestMapping(value="", method=RequestMethod.POST)
  public String postBook(@RequestBody Book book) {
    books.put(book.getId(), book);
    return "success";
  }

  @ApiOperation(value = "      ", notes = "  url id       ")
  @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Long", paramType = "path")
  @RequestMapping(value = "/{id}", method = RequestMethod.GET)
  public Book getBook(@PathVariable Long id) {
    return books.get(id);
  }
}

5:SpringBoot 시작 클래스 만 들 기:

@SpringBootApplication
@ComponentScan(basePackages={"com"}) 
public class Application {
  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }
}

STEP 3:Swagger 시작
OK,여기까지 입 니 다.모든 Swagger 를 설정 하 였 습 니 다.이 때 방문http://localhost:8080/swagger-ui.html#/greeting-controller。Swagger-UI 를 볼 수 있 습 니 다.아래 그림 과 같다.

마찬가지 로@RequestMapping()의 경로 에 따라 접근 할 수 있 고 API 에서 테스트 할 수 있 습 니 다.여기 서 제 가 시범 을 보 여 드 리 겠 습 니 다.
구덩이!!!!내 가 설정 하 는 과정 에서 발생 한 오류;
제 파일 구 조 를 먼저 보 내 드 리 겠 습 니 다.

1:모든 것 이 설정 되 어 있 지만 API 는 아무것도 표시 되 지 않 습 니 다.그림 에서 보 듯 이:

이것 이 바로 내 가 위 에서 말 한 문제 이다.RequestHandler Selectors.basePackage("com.swagger")
이 곳 은 swagger 가 불 러 올 인터페이스 가 있 는 가방 이름 을 설정 합 니 다.이 가방 에 있 는 모든 컨트롤 러 를 스 캔 하 러 갑 니 다.여러분,제 파일 구 조 를 보 세 요.
RequestHandler Selectors.basePackage("com")를 설정 하면 com.swagger 를 포함 한 모든 com 패키지 의 컨트롤 러 를 스 캔 합 니 다.그리고 com.controller.효 과 는 이렇다.

RequestHandlerSelectors.basePackage("com.swagger")나 RequestHandlerSelectors.basePackage("com.swagger")만 따로 설정 하면 됩 니 다.그럼 하나 나 와 요.

2:RequestHandler Selectors.basePackage("com")를 설 정 했 지만 API 는 하나만 표시 되 고 Controller 가 직접 접근 하 는 주 소 를 표시 하지 않 아 도 오류 가 발생 했 습 니 다.그림 참조:


이 럴 때 는 스프링 부츠 가 문제 일 수도 있어 요.그 는 결코 너의 다른 controller 에 불 러 오지 않 았 다.
SpringBoot 시작 클래스 와 Controller 클래스 는 같은 가방 에 있어 야 합 니 다.contrller 는 부모 클래스 에 있어 야 합 니 다.
이때 두 가지 해결 방안 이 있다.
1.불 러 오지 않 은 Conrtoller 류 를 SpringBoot 시작 클래스 가 있 는 가방 으로 이동 합 니 다.또는 가방 이름 을 시작 클래스 의 하위 가방 으로 바 꿉 니 다.
2.상기 코드 와 같이 시작 클래스 에 설명 을 추가 합 니 다:@Componentscan(basePackages={"com"}).이 설명 은 모든 com 패키지 의 controller 를 스 캔 하고 불 러 옵 니 다.
왜 나 는 Greeting Controller 에 rest 방법 을 쓰 지 않 았 습 니까?근 데 API 에 다 나 오 는데?
이것 은@RequestMapping()을 사용 해 야 합 니 다.해명 했다.
1.@RequestMapping(value="/swagger")또는@RequestMapping("/swagger")이 이렇게 쓸 때 모든 method 를 불 러 옵 니 다.
2.@RequestMapping(value="/swagger",method=RequestMethod.POST)은 mathod 를 설정 할 때 설정 한 method 만 생 성 합 니 다.
이상 의 SpringBoot 통합 Swagger 가 api 문 서 를 구축 하 는 작업 은 바로 작은 편집 이 여러분 에 게 공유 하 는 모든 내용 입 니 다.참고 가 되 고 저 희 를 많이 사랑 해 주 셨 으 면 좋 겠 습 니 다.