SpringBoot Swagger Api 를 우아 하 게 통합 하여 문 서 를 자동 으로 만 드 는 방법

머리말
좋 은 지속 가능 한 납품 프로젝트 입 니 다.프로젝트 설명 과 인터페이스 문 서 는 없어 서 는 안 됩 니 다.swagger api 는 우리 가 api 문 서 를 자동 으로 생 성 할 수 있 도록 도와 줄 수 있 습 니 다.따로 추가 적 으로 쓸 필요 가 없고 침입 식 이 없 으 며 앞 뒤의 소통 을 편리 하 게 줄 이 고 검색 과 테스트 인 터 페 이 스 를 통 해 팀 의 개발 효율 을 향상 시 켜 신인 들 이 프로젝트 를 이해 하 는 데 편리 합 니 다.남 은 시간 에 여동생 을 만 나 러 갈 수 있 습 니 다.
통합 swagger api
여기 서 우 리 는 스스로 swagger api 를 통합 하 는 것 이 비교적 번 거 롭 습 니 다.여러 개의 가방 을 가 져 와 야 합 니 다.큰 신 이 우리 에 게 바퀴 kinfe4j 가 SpringBoot 의 시작 항목 에 직접 대응 하 는 것 을 써 주 었 습 니 다.그리고 원래 의 사용 기능 에 영향 을 주지 않 고 인터페이스 ui 가 미화 기능 을 하여 우리 가 직접 이것 을 통합 시 켰 으 면 좋 겠 습 니 다.

        <!--api   -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.1</version>
        </dependency>

와 같다,흡사...

kinfe4j 공식 문서 여 기 를 클릭 하 세 요.
사용자 정의 설정 정보
swagger 에 더 많은 인터페이스 설명 을 설정 합 니 다.

package cn.soboys.core.config;

import cn.hutool.core.collection.CollUtil;
import cn.soboys.core.ret.ResultCode;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Response;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import javax.annotation.Resource;
import java.util.Arrays;
import java.util.List;

/**
 * @author kenx
 * @version 1.0
 * @date 2021/6/21 16:02
 * api    
 */
@Configuration
public class SwaggerConfigure {
    @Resource
    private SwaggerProperty swaggerProperty;

    /**
     *   api   
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30).globalResponses(HttpMethod.POST, this.responseList()) //  respons  
                .apiInfo(apiInfo(swaggerProperty))  //    
                .select()
                //    
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  // ApiOperation   controller   api  
                .apis(RequestHandlerSelectors.basePackage(swaggerProperty.getBasePackage())) //   
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(SwaggerProperty swagger) {
        return new ApiInfoBuilder()
                //  
                .title(swagger.getTitle())
                //  
                .description(swagger.getDescription())
                //        （  ，  ，  ）
                .contact(new Contact(swagger.getAuthor(), swagger.getUrl(), swagger.getEmail()))
                //  
                .version(swagger.getVersion())
                //  
                .license(swagger.getLicense())
                //    
                .licenseUrl(swagger.getLicenseUrl())
                .build();
    }

    /**
     *   response     
     * @return
     */
    private List<Response> responseList() {
        List<Response> responseList = CollUtil.newArrayList();
        Arrays.stream(ResultCode.values()).forEach(errorEnum -> {
            responseList.add(
                    new ResponseBuilder().code(errorEnum.getCode().toString()).description(errorEnum.getMessage()).build()
            );
        });
        return responseList;
    }
}

api 문서 설정 모듈 정 보 를 추출 하여 속성 파일 로 재 활용 하기 편리 합 니 다.

package cn.soboys.core.config;

import lombok.Data;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringBootConfiguration;

/**
 * @author kenx
 * @version 1.0
 * @date 2021/6/21 16:01
 * api     
 */
@Data
@SpringBootConfiguration
public class SwaggerProperty {
    /**
     *     api     
     */
    @Value("${swagger.basePackage}")
    private String basePackage;
    /**
     * api     
     */
    @Value("${swagger.title}")
    private String title;
    /**
     * api     
     */
    @Value("${swagger.description}")
    private String description;
    /**
     * api     
     */
    @Value("${swagger.version}")
    private String version;
    /**
     * api      
     */
    @Value("${swagger.author}")
    private String author;
    /**
     * api       
     */
    @Value("${swagger.url}")
    private String url;
    /**
     * api      
     */
    @Value("${swagger.email}")
    private String email;
    /**
     * api        
     */
    @Value("${swagger.license}")
    private String license;
    /**
     * api         
     */
    @Value("${swagger.licenseUrl}")
    private String licenseUrl;
}

간단히 사용 하 다
컨트롤 러 에 swagger 주 해 를 추가 합 니 다.

@Slf4j
@Api(tags = "  ")
public class LoginController {
    private final IUsersService userService;

    @PostMapping("/login")
    @ApiOperation("    ")
    public String login(@RequestBody UserLoginParams userLoginParams) {
        Users u = userService.login(userLoginParams);
        return "ok";
    }
}

접근 권한 을 사용 하면 swagger 관련 uri 를 익명 으로 접근 할 수 있 도록 해 야 합 니 다.

/swagger**/**
/webjars/**
/v3/**
/doc.html

서 비 스 를 다시 시작 합 니 다.api 문서 접근 링크 는/doc.html 인터페이스 는 다음 과 같 습 니 다.

원래 의 인터페이스 UI 에 비해 더욱 예 뻐 지고 정보 가 더욱 완선 되 며 기능 이 더욱 강해 집 니 다.
Swagger 상용 주해

Api 태그
요청 한 클래스 에 사용 하여 클래스 에 대한 설명 을 나타 내 는 것 도 swagger 2 의 자원 임 을 나타 낸다.
인자:

tags:이러한 역할 을 설명 하고 매개 변 수 는 배열 이 며 여러 개 를 채 울 수 있 습 니 다

value="이 매개 변 수 는 의미 가 없고 UI 인터페이스 에 표시 되 지 않 기 때문에 설정 하지 않 아 도 됩 니 다"

description="사용자 기본 정보 조작"
ApiOperation 태그
요청 하 는 방법 에 http 요청 동작 을 표시 합 니 다.
인자:

value 는 방법 설명 에 사용 된다

notes 는 내용 을 제시 하 는 데 사 용 됩 니 다

tags 는 다시 그룹 을 나 눌 수 있 습 니 다(상황 에 따라 사용)

Apiparam 태그
요청 방법 에 있어 서 요청 매개 변수,필드 설명 에 사용 합 니 다.매개 변수 에 메타 데이터 추가(설명 또는 필수 여부 등)
인자:
namec 매개 변수 명

valueC 매개 변수 설명

required C 필수 여부
ApiModel 태그
자바 실체 클래스 에서 클래스 에 대한 설명 을 표시 하고 매개 변 수 는 실체 클래스 로 수신 합 니 다.
인자:
valueC 는 대상 명 을 나타 낸다설명 C 설명
모두 생략 할 수 있다
ApiModelproperty 태그
방법,필드 에 사용 하기;model 속성 에 대한 설명 이나 데이터 조작 변경 을 표시 합 니 다.
인자:
valueC 필드 설명namec 재 작성 속성 이름
dataTypeC 재 작성 속성 유형required C 필수 여부example C 예시 설명hiddenc 숨 기기

@ApiModel(value="user  ",description="    user")
public class User implements Serializable{
    private static final long serialVersionUID = 1L;
     @ApiModelProperty(value="   ",name="username",example="xingguo")
     private String username;
     @ApiModelProperty(value="  ",name="state",required=true)
      private Integer state;
      private String password;
      private String nickName;
      private Integer isDeleted;
 
      @ApiModelProperty(value="id  ",hidden=true)
      private String[] ids;
      private List<String> idList;
     //  get/set
}

ApiIgnore 태그
요청 클래스 나 방법 에 사용 되 며,swagger 에 표시 되 지 않 아 도 됩 니 다.
ApiImplicitParam 태그
방법 으로 단독 요청 파 라미 터 를 표시 합 니 다
ApiImplicitParams 태그
방법 에 사용,여러 개의@ApiImplicitParam 포함
인자:
namec 매개 변수 명

valueC 매개 변수 설명

dataTypeC 데이터 형식paramTypeC 매개 변수 유형example C 예시 설명

  @ApiOperation("    ")
  @GetMapping("select")
  //@ApiImplicitParam(name="name",value="   ",dataType="String", paramType = "query")
  @ApiImplicitParams({
  @ApiImplicitParam(name="name",value="   ",dataType="string", paramType = "query",example="xingguo"),
  @ApiImplicitParam(name="id",value="  id",dataType="long", paramType = "query")})
  public void select(){
 
  }

총결산
4.567917.실체 류 와 인터페이스 에 주석 정 보 를 추가 할 수 있 습 니 다.4.567918.
인터페이스 문서 실시 간 업데이트
온라인 테스트
4

kinfe4j 는 swagger API 에서 만 강화 하고 기 존의 어떠한 사용 도 바 꾸 지 않 으 며 사용 기능 을 더 증가 합 니 다.

여 기 를 누 르 면 kinfe4j 홈 페이지 문서 에 들 어 갑 니 다.
SpringBoot 가 어떻게 우아 하 게 Swagger Api 를 통합 하여 문 서 를 자동 으로 생 성 하 는 지 에 관 한 이 글 은 여기까지 소개 되 었 습 니 다.더 많은 SpringBoot 통합 Swagger Api 내용 은 우리 의 이전 글 을 검색 하거나 아래 의 관련 글 을 계속 찾 아 보 세 요.앞으로 많은 응원 부 탁 드 리 겠 습 니 다!