SpringBoot 통합 인터페이스 관리 도구 Swagger 사용 방법

1. Swagger 소개

Swagger는 Swagger를 통해 프로젝트의 대화형 문서, 클라이언트 SDK 자동 생성 및 기타 기능을 얻을 수 있는 일련의 RESTful API 도구입니다.

Swagger의 목표는 사람과 컴퓨터가 소스 코드나 문서를 보거나 다양한 서비스의 네트워크 트래픽 감지에 실패하지 않고도 이를 발견하고 이해할 수 있도록 REST API에 대한 언어 독립적인 표준 인터페이스를 정의하는 것입니다. Swagger를 통해 서비스가 정의되면 소비자는 소량의 구현 로직을 통해 원격 서비스와 상호 작용할 수 있습니다.

2. Springboot는 swagger를 통합합니다

Spring Boot를 사용하여 Swagger를 통합하는 아이디어는 주석을 사용하여 API 문서에 표시되어야 하는 정보를 표시하는 것입니다. 표시된 주석을 기반으로 해당 API 문서를 생성합니다. 프로젝트에서. Swagger는 세계에서 가장 널리 사용되는 API 도구로 알려져 있으며 API 관리를 위한 완벽한 솔루션을 제공합니다. 여기서는 가장 일반적으로 사용되는 사용자 정의 콘텐츠에 대해 기본적으로 설명합니다.

1. Swagger 좌표 추가

Swagger 3를 통합하는 Spring Boot는 매우 간단합니다. 종속성을 도입하고 기본 구성만 수행하면 됩니다.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2. Swagger Helloword 구현

2.1. springboot 프로젝트 만들기

Swagger API 문서 기능을 활성화하려면 @EnableOpenApi 주석을 추가하세요

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;

@SpringBootApplication
@EnableOpenApi  //启动swagger api文档注解
public class SpringBootWithSwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootWithSwaggerApplication.class, args);
    }

}

2.2.2.3. 액세스 주소

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
public class SwaggerController {
    @GetMapping ("hello")
    public String hello(String params) {
        return "hello swagger"+" param为:"+params;
    }
}

3. 일반적으로 사용되는 구성 주석

Swagger는 주석을 사용하여 인터페이스가 인터페이스 이름, 요청 방법, 매개변수, 반환 정보 등을 포함하는 문서를 생성함을 나타냅니다.

1,

Api

주석

ApiOperation

주석

@Api

• 은 클래스에 사용되며 @API에는 값과 태그라는 두 가지 속성이 있음을 나타냅니다.

  생성된 API 문서는 태그에 따라 분류됩니다. 직설적으로 말하면 이 컨트롤러의 모든 인터페이스에서 생성된 인터페이스 문서는 태그 목록 아래에 있습니다. 태그에 여러 값이 있으면 여러 목록이 생성되고 각 목록이 표시됩니다. 모든 인터페이스

값 함수는 태그와 같지만 여러 값을 가질 수 없습니다.

http://localhost:8080/swagger-ui/index.html

@ApiOperation

• 은 http 요청의 작업을 나타내는 메서드에 사용됩니다.

  语法:
    @Api(tags = "用户操作")
    或
    @Api(tags = {"用户操作","用户操作2"})

  사례: @Api 및 @ApiOperation 사용 API 문서를 생성하려면

语法:
    @ApiOperation(value = "", 
                  notes = "", 
                  response = )
属性说明：
  value：方法说明标题
  notes：方法详细描述
  response：方法返回值类型

2,

Apiimplicitparams

주석 및

apiimplicitparam

@apiimplicitparams 주석 및 @apiimplicitparam

은 메소드에서 비 관습 매개 변수에 사용됩니다 (파라미터가 간단한 유형에 바인딩 될 때 사용). explain

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
@Api(tags = {"操作用户"})
public class SwaggerController {
    @GetMapping ("hello")
    @ApiOperation(value = "swagger请求",notes = "阿水的第一个swagger请求",response = String.class)
    public String hello(String params) {
        return "hello swagger"+" param为:"+params;
    }
}

참고: @ApiImplicitParam의 name 속성은 @RequestParam 또는 @PathVariable 값을 반영해야 합니다. Case: @ApiImplicitParams 주석과 @ApiImplicitParam을 사용하여 메서드 매개변수를 설명합니다.

语法:
@ApiImplicitParams(value = {
     @ApiImplicitParam(name="", value = "", type = "", required = true, paramType = "", defaultValue  = "")
})

属性说明：
    name:形参名称
    value:形参的说明文字
    type:形参类型
    required:该参数是否必须  true|false
    paramType: 用于描述参数是以何种方式传递到 Controller 的，它的值常见有： path, query, body 和 header 
        path 表示参数是『嵌在』路径中的，它和 @PathVariable 参数注解遥相呼应；
    	query 表示参数是以 query string 的形式传递到后台的（无论是 get 请求携带在 url 中，还是 post 请求携带在请求体中），它和 @RequestParam 参数注解遥相呼应；
    	header 表示参数是『藏在』请求头中传递到后台的，它和 @RequestHeader 参数注解遥相呼应的。
    	form 不常用.
    defaultValue :参数默认值

3. ApiModel 주석과 ApiModelProperty

@ApiModel

은 엔터티의 매개변수 수신 설명을 나타내기 위해 엔터티 클래스에 사용됩니다. 수업.

• import io.swagger.annotations.Api;
  import io.swagger.annotations.ApiImplicitParam;
  import io.swagger.annotations.ApiImplicitParams;
  import io.swagger.annotations.ApiOperation;
  import org.springframework.web.bind.annotation.GetMapping;
  import org.springframework.web.bind.annotation.RestController;
  
  /**
   * @author 阿水
   * @create 2023-04-11 9:54
   */
  @RestController()
  @Api(tags = {"操作用户"})
  public class SwaggerController {
      @GetMapping ("hello")
      @ApiOperation(value = "swagger请求",notes = "阿水的第一个swagger请求",response = String.class)
      @ApiImplicitParams(value ={
              @ApiImplicitParam(name="param1",
                      value = "参数名1",
                      type = "String",
                      required = true,
                      paramType = "query",
                      defaultValue  = "阿水所想的默认值1" ),
              @ApiImplicitParam(name="param2",
                      value = "参数名2",
                      type = "String",
                      required = true,
                      paramType = "query",
                      defaultValue  = "阿水所想的默认值2" )
      })
      public String hello(String param1,String param2) {
          return "hello swagger"+" param1为:"+param1+"param2为"+param2;
      }
  }

  4. ApiResponse 및 ApiResponses
  @ApiResponses 주석과 @ApiResponse는 HTTP 요청

@ApiModel("用户类")
@Data
public class Users {

    @ApiModelProperty(value = "编码：主键")
    private Integer id;

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "密码")
    private String password;

}

5의 응답을 설명하기 위해 SwaggerConfig 구성 클래스를 생성합니다. : (메소드 중 하나는 다른 메소드에 대한 보조 준비입니다.)

api() 메소드는 시작 시 초기화되는 @Bean을 사용하고 인스턴스 Docket(Swagger API 요약 객체)을 반환합니다. apis(RequestHandlerSelectors .basePackage("xxx.yyy.zzz"))는 스캔해야 하는 패키지 경로를 지정합니다. 이 경로 아래의 Controller 클래스만 Swagger API 문서를 자동으로 생성합니다.

/**
     * 添加用户
     *
     * @param user
     * @return
     */
    @PostMapping("/add")
    @ApiOperation(value = "添加用户",notes = "添加用户信息",response = ResponseResult.class)
    @ApiResponses({ @ApiResponse(code = 200, message = "添加成功", response = ResponseResult.class),
            	    @ApiResponse(code = 500, message = "添加失败", response = ResponseResult.class) })
    public ResponseResult<Void> addUser(@RequestBody User user) {
        //获得生成的加密盐
        user.setSalt(SaltUtils.getSalt());
        int n = userService.addUser(user);
        if (n > 0) {
            return new ResponseResult<Void>(200, "添加成功");
        }
        return new ResponseResult<Void>(500, "添加失败");
    }

apiInfo() 메소드 구성은 상대적으로 중요합니다. 기본 구성 페이지에 표시되는 기본 정보에는 제목, 설명, 버전, 서비스 약관 등이 포함됩니다. ApiInfo 클래스의 소스 코드를 보면 찾을 수도 있습니다. 4. Springsecurity는 swagger

4.1을 통합하고 릴리스 주소

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger配置类
 */
@Configuration  //项目启动时加载此类
public class SwaggerConfig {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                // 此处自行修改为自己的 Controller 包路径。
                .apis(RequestHandlerSelectors.basePackage("com.lps.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("阿水的项目接口文挡")
                .description("阿水的 Project Swagger2 UserService Interface")  //说明信息
                .termsOfServiceUrl("http://localhost:8080/swagger-ui/index.html") //文档生成的主页地址
                .version("1.0")  //文档版本
                .build();
    }
}

4.2를 구성하고 UI

를 대체합니다. 위의 전체 프로세스가 완료되었지만 생성된 인터페이스 문서 페이지는 실제로 마음에 들지 않습니다. 많은 사람들이 중국어 사용에 적합하지 않다고 느끼기 때문에 다른 UI 테스트 페이지를 제공하는 마스터가 있습니다. 이 페이지는 여전히 널리 사용되고 있습니다.

다음 종속성을 가져오고 프로젝트를 다시 시작한 후 http://localhost:8080/doc.html

  http.authorizeRequests().antMatchers( "/swagger-ui.html",
                "/swagger-ui/*",
                "/swagger-resources/**",
                "/v2/api-docs",
                "/v3/api-docs",
                "/webjars/**").permitAll()
                .anyRequest().authenticated();

주소를 방문하세요.

위 내용은 SpringBoot 통합 인터페이스 관리 도구 Swagger 사용 방법의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!