springboot swagger를 이용하여api 문서 구축

앞말

Swagger는 RESTFUL 인터페이스의 문서 온라인 자동 생성 + 기능 테스트 기능 소프트웨어입니다.본고는 프로젝트에서 swagger를 통합하는 방법과 흔히 볼 수 있는 문제를 간단하게 소개했다.프로젝트 원본을 깊이 있게 분석하고 더 많은 내용을 알고 싶으면 참고 자료를 보십시오.
Swagger는 RESTful 스타일의 웹 서비스를 생성, 설명, 호출, 시각화하는 데 사용되는 규범적이고 완전한 프레임워크입니다.전체 목표는 클라이언트와 파일 시스템을 서버로 똑같은 속도로 업데이트하는 것이다.파일의 방법, 매개 변수와 모델이 서버에 밀접하게 통합된 코드로 API가 시종일관 동기화를 유지할 수 있도록 한다.Swagger는 배포 관리 및 강력한 API를 쉽게 사용할 수 있게 해 줍니다.

swagger 의존 추가

1
2
3
4
5
6
7
8
9
10
11

<dependency>
  <groupId>io.springfoxgroupId>
  <artifactId>springfox-swagger2artifactId>
  <version>2.6.1version>
dependency>

<dependency>
  <groupId>io.springfoxgroupId>
  <artifactId>springfox-swagger-uiartifactId>
  <version>2.6.1version>
dependency>

swagger 설정 추가

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

@EnableSwagger2
public class  {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ybf.activity.web.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return   springboot swagger api n> new ApiInfoBuilder()
                .title("springboot swagger api ")
                .description(" restful ，http://luckystar88.github.io/")
                .termsOfServiceUrl("http://luckystar88.github.io/")
                .version("1.0")
                .build();
    }
}

스프링 부트의 패키지 구조를 주의하십시오. 그렇지 않으면 설정이 잘못될 수 있습니다.예시 프로그램의 패키지 구조:com.ybf.activity.web|———————-|config—————————–Swagger2.java———————-Application.java

인터페이스 방법에 주석을 사용하여 설명 정보를 추가합니다

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

@ApiOperation(value = " ",notes = " id ")
@ApiImplicitParam(name = "id",value = " id",required = true,dataType = "int",paramType = "path")
@RequestMapping(value = "/student/{id}",method = RequestMethod.GET)
@ResponseBody
public Student student(@PathVariable int id) {
    return studentMapper.getById(id);
}

@ApiOperation(value = " （ ）",notes = " ")
@ApiImplicitParam(name="pageNo",value = " ",required = true,dataType = "int",paramType = "path")
@RequestMapping(value = "/student/page/{pageNo}",method = RequestMethod.GET)
@ResponseBody
public List selectStudentByPage(@PathVariable int pageNo) {
    if (pageNo > 0) {
        PageHelper.startPage(pageNo,3); 
    }
    return studentMapper.sel();
}

기본적으로 모든 메서드에 API 문서가 생성되며 메서드가 필요하지 않으면 @ApiIgnore를 추가할 수 있습니다.
SpringBoot 프로그램을 시작하고 브라우저 입력: /swagger-ui.html 효과를 볼 수 있습니다.
요청을 누르면 자세한 내용을 볼 수 있습니다. 파라미터를 입력하고 Try it out 단추를 누르면 응답을 볼 수 있습니다.