SpringBoot는 Swagger2를 통합합니다.
일부 오래된 프로젝트의 사후 개발을 수행할 때 대부분의 회사는 프로젝트 관리자가 작성한 개발 문서를 기반으로 프로젝트를 수행하고 배경에 있는 프로그래머는 인터페이스 문서에 따라 인터페이스를 개발합니다. 약간의 변경 후 코드가 변경되었지만 문서가 즉시 업데이트되지 않아 나중에 문서를 읽을 때 코드와 일치하지 않아 일부 문제가 발견되었습니다.
이전에는 단어로 작성된 인터페이스 문서를 사용했는데 대부분의 경우 다음과 같은 몇 가지 문제가 있습니다.
- 인터페이스 문서 및 코드의 실시간 업데이트
- 인터페이스 설명서에 대한 사양 문제
- 인터페이스 문서가 너무 많아 관리가 불편함
그래서 API 문서를 자동으로 생성하는 Swagger의 도구가 등장했습니다.그 장점은 다음과 같습니다.
- Swagger는 자동으로 API 문서를 생성하고 온라인에서 기능을 테스트할 수 있습니다.
- Swagger는 SpringBoot와 신속하게 통합 및 사용할 수 있습니다.
Swagger2 튜토리얼
1. pom에 종속성 도입
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
2. Swagger2의 구성 클래스 작성
/**
* Swagger2 配置类
* 在与spring boot 集成时，放在与application.java 同级的目录下
* 通过@Configuration注解，让spring来加载该配置
* 再通过@EnableSwagger2注解来启动Swagger2
*/
@Configuration
@EnableSwagger2
public class Swagger2 {
/**
* 创建API应用
* appinfo()增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例，用来控制那些接口暴露给Swagger来展现
* 本例采用置顶扫描的包路径来定义指定要建立API的目录
*
* @return
*/
@Bean
public Docket createRestApi() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.Jason.chat"))
.paths(PathSelectors.any()).build();
return docket;
}
/**
* 创建改API的基本信息（这些基本信息会展示在文档页面中）
* 访问地址： http://项目实际地址/swagger-ui.html
* @return
*/
public ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")
.description("简单优雅的restfun风格，https://blog.csdn.net/weixin_43650254")
.termsOfServiceUrl("https://blog.csdn.net/weixin_43650254")
.contact("Jason")
.version("1.0")
.build();
}
}
3. 주석을 사용하여 API 문서를 자동으로 생성하는 Swagger 실현
@Api: 클래스의 기능을 설명하기 위해 클래스에서 사용됩니다.
@ApiOperation: API에 메서드 설명을 추가하기 위한 주석입니다.
@ApiImplicitParams : 매개변수 설명 집합을 포함하는 메서드에 사용됩니다.
@ApiImplicitParam: 메서드 입력 매개변수에 설명을 추가하기 위해 주석을 추가하는 데 사용됩니다.
@ApiResponses: 응답 집합을 나타내는 데 사용됩니다.
@ApiResponse: @ApiResponses에서 사용, 일반적으로 잘못된 응답 메시지를 표현하는 데 사용
-
코드: 숫자(예: 400)
-
메시지: "요청 매개변수가 채워지지 않았습니다"와 같은 정보
-
응답: 예외를 발생시킨 클래스
@ApiModel: Model 정보를 기술한다(일반적으로 @ApiImplicitParam 어노테이션을 사용하여 요청 파라미터를 기술할 수 없을 때 사용)
- @ApiModelProperty: 모델의 속성을 설명합니다.
참고: @ApiImplicitParam의 매개변수 설명:
| 매개변수 | 설명하다 |
|---|---|
| paramType: 매개변수가 배치되는 위치 지정 | 헤더: 요청 매개변수는 요청 헤더에 배치, @RequestHeader를 사용하여 쿼리 가져오기 : 요청 매개변수는 요청 주소에 배치, @RequestParam을 사용하여 경로 가져오기 : (편안한 인터페이스용) –> 요청 매개변수 가져오기: @PathVariable 본문: (일반적이지 않음) used) 형태 (흔히 사용되지 않음) |
| 이름: 매개변수 이름 | |
| 데이터 유형: 매개변수 유형 | |
| required: 매개변수를 전달해야 하는지 여부 | 사실 | 거짓 |
| 값: 매개변수의 의미 설명 | |
| defaultValue: 매개변수의 기본값 |