springboot3 project uses swagger3

Article directory

• • springboot3 project uses swagger3
  • • • rely
      • swaggerConfig configuration
      • Entity class example
      • Control layer example
      • • Universal return result encapsulation
      • Annotation description
      • address
      • git common commands

springboot3 project uses swagger3

Dependencies

 <!--swagger3-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.1.0</version>
        </dependency>


    <repositories>
        <!--Alibaba Cloud Image-->
        <repository>
            <id>alimaven</id>
            <name>aliyun maven</name>
            <url>https://maven.aliyun.com/nexus/content/groups/public/</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
    </repositories>

swaggerConfig configuration

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {<!-- -->
    @Bean
    public OpenAPI springShopOpenAPI() {<!-- -->
        return new OpenAPI()
                .info(new Info().title("title")
                        .contact(new Contact())
                        .description("My API Documentation")
                        .version("v1")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("External Document")
                        .url("https://springshop.wiki.github.org/docs"));
    }
}

Example of entity class

import com.alibaba.excel.annotation.ExcelProperty;
import com.alibaba.excel.annotation.write.style.ColumnWidth;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;

import java.util.Date;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Accessors(chain = true)
@Schema(name = "Employee", description = "$!{table.comment}")
public class Emp {<!-- -->
    @ExcelProperty("ID")
    @Schema(description = "ID")
    private int id;
    @ExcelProperty("username")
    @Schema(description = "username")
    private String names;
    @ExcelProperty("Salary")
    @Schema(description = "salary")
    private double salary;
    @ExcelProperty("birthday")
    @Schema(description = "birthday")
    private Date birthday;
    @ColumnWidth(20)
    @ExcelProperty("avatar")
    @Schema(description = "avatar")
    private String photo;
    
// @ColumnWidth(20)
// @DateTimeFormat("yyyy-MM-dd HH:mm:ss")
// @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
// @ExcelProperty("Creation Date")
// private Date u_create_time;
}

Control layer example

 @Operation(summary = "User List")
    @GetMapping("/selectAll")
    public Result<List<Emp>> selectAll() {<!-- -->
        return Result.success(excelMapper.selectEmpAll());
    }

Universal return result packaging

import lombok.AllArgsConstructor;
import lombok.Getter;

@Getter
@AllArgsConstructor
public enum ResultCode {<!-- -->
    SUCCESS(200, "success"),
    REQUEST_ERROR(400, "Parameter verification failed"),
    FAILURE(500, "System Error");

    private final int code;
    private final String msg;
}

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Getter;
import lombok.Setter;
import lombok.extern.slf4j.Slf4j;

@Builder(toBuilder = true)
@AllArgsConstructor
@Setter
@Getter
@Slf4j
public class Result<T> {<!-- -->
    /**
     * Prompt information
     */
    @Schema(description = "prompt information")
    private String message;
    /**
     * whether succeed
     */
    @Schema(description = "Whether it was successful")
    private boolean success;
    /**
     * Return status code
     */
    @Schema(description = "Return status code")
    private Integer code;
    /**
     * data
     */
    @Schema(description = "data")
    private T data;

    public Result() {<!-- -->
    }

    public static Result success() {<!-- -->
        Result Result = new Result();
        Result.setSuccess(Boolean.TRUE);
        Result.setCode(ResultCode.SUCCESS.getCode());
        Result.setMessage(ResultCode.SUCCESS.getMsg());
        return Result;
    }

    public static Result success(String msg) {<!-- -->
        Result Result = new Result();
        Result.setMessage(msg);
        Result.setSuccess(Boolean.TRUE);
        Result.setCode(ResultCode.SUCCESS.getCode());
        return Result;
    }

    public static Result success(Object data) {<!-- -->
        Result Result = new Result();
        Result.setData(data);
        Result.setSuccess(Boolean.TRUE);
        Result.setCode(ResultCode.SUCCESS.getCode());
        Result.setMessage(ResultCode.SUCCESS.getMsg());
        return Result;
    }

    /**
     * Return failure message
     *
     * @return Result
     */
    public static Result failure() {<!-- -->
        Result Result = new Result();
        Result.setSuccess(Boolean.FALSE);
        Result.setCode(ResultCode.FAILURE.getCode());
        Result.setMessage(ResultCode.FAILURE.getMsg());
        return Result;
    }

    /**
     * Return failure message
     *
     * @param msg failure information
     * @return Result
     */
    public static Result failure(String msg) {<!-- -->
        Result Result = new Result();
        Result.setSuccess(Boolean.FALSE);
        Result.setCode(ResultCode.FAILURE.getCode());
        Result.setMessage(msg);
        return Result;
    }

    public static Result failure(Integer code, String msg) {<!-- -->
        Result Result = new Result();
        Result.setSuccess(Boolean.FALSE);
        Result.setCode(code);
        Result.setMessage(msg);
        return Result;
    }


    public static Result failure(String msg, ResultCode exceptionCode) {<!-- -->
        Result Result = new Result();
        Result.setMessage(msg);
        Result.setSuccess(Boolean.FALSE);
        Result.setCode(exceptionCode.getCode());
        Result.setData(exceptionCode.getMsg());
        return Result;
    }

    /**
     * Return failure message
     *
     * @param exceptionCode error information enumeration
     * @return Result
     */
    public static Result failure(ResultCode exceptionCode) {<!-- -->
        Result Result = new Result();
        Result.setSuccess(Boolean.FALSE);
        Result.setCode(exceptionCode.getCode());
        Result.setMessage(exceptionCode.getMsg());
        return Result;
    }

    /**
     * Return failure message
     *
     * @param exceptionCode error information enumeration
     * @param msg Custom error message
     * @return Result
     */
    public static Result failure(ResultCode exceptionCode, String msg) {<!-- -->
        Result Result = new Result();
        Result.setMessage(msg);
        Result.setSuccess(Boolean.FALSE);
        Result.setCode(exceptionCode.getCode());
        return Result;
    }

}

Annotation description

swagger2	OpenAPI 3	Annotation location
@Api	@Tag(name = “Interface Class Description”)	On the Controller class
@ApiOperation	@Operation(summary = “Interface method description”)	On the Controller method
@ApiImplicitParams	@ Parameters	On the Controller method
@ApiImplicitParam	@Parameter(description=”Parameter Description”)	In @Parameters on the Controller method
@ApiParam	@Parameter(description=”Parameter Description”)	In the Controller method On the parameter
@ApiIgnore	@Parameter(hidden = true) or @Operation(hidden = true) or @Hidden	–
@ApiModel	@Schema	DTO class
@ApiModelProperty	@Schema	DTO attribute

Access address

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

Git common commands

git tag -a v0.1.7 -m "Complete image upload interface"
git push origin tag v0.1.7
git push origin --tags

git tag -a v0.1.6 -m "Complete Excel data import and export"
git push origin tag v0.1.6
git push origin --tags

git tag -a v0.1.5 -m "Complete verification code generation interface"
git push origin tag v0.1.5
git push origin --tags

git tag -a v0.1.4 -m "Interface parameter verification, unified exception interception"
git push origin tag v0.1.4
git push origin --tags

git tag -a v0.1.3 -m "Encapsulate Result and unify return values"
git push origin tag v0.1.3
git push origin --tags

git tag -a v0.1.2 -m "restful and rpc"
git push origin tag v0.1.2
git push origin --tags

git tag -a v0.1.1 -m "Support mybatis, connect to the database, and complete basic additions, deletions, modifications and checks"
git push origin tag v0.1.1
git push origin --tags

git tag -a v0.1 -m "Initialization project, spring boot 3 + swagger 3"
git push origin tag v0.1
git push origin --tags