swagger,swagger-beauty,security,rbac-shiro

Posted 2023-04-07 激流勇进_38193118

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了swagger,swagger-beauty,security,rbac-shiro相关的知识，希望对你有一定的参考价值。

spring-boot-demo-swagger

集成原生 swagger ，自动生成 API 文档。>
启动项目，访问地址：http://localhost:8080/demo/swagger-ui.html#/

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <artifactId>spring-boot-demo-swagger</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>jar</packaging>
    <parent>
        <groupId>com.xkcoding</groupId>
        <artifactId>spring-boot-demo</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
        <swagger.version>2.9.2</swagger.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>$swagger.version</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>$swagger.version</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>
    <build>
        <finalName>spring-boot-demo-swagger</finalName>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Swagger2Config.java

@Configuration
@EnableSwagger2
public class Swagger2Config 
    @Bean
    public Docket createRestApi() 
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xkcoding.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    
    private ApiInfo apiInfo() 
        return new ApiInfoBuilder().title("spring-boot-demo")
                .description("这是一个简单的 Swagger API 演示")
                .contact(new Contact("Yangkai.Shen", "http://xkcoding.com", "237497819@qq.com"))
                .version("1.0.0-SNAPSHOT")
                .build();

UserController.java

主要演示API层的注解。

@RestController
@RequestMapping("/user")
@Api(tags = "1.0.0-SNAPSHOT", description = "用户管理", value = "用户管理")
@Slf4j
public class UserController 
    @GetMapping
    @ApiOperation(value = "条件查询（DONE）", notes = "备注")
    @ApiImplicitParams(@ApiImplicitParam(name = "username", value = "用户名", dataType = DataType.STRING, paramType = ParamType.QUERY, defaultValue = "xxx"))
    public ApiResponse<User> getByUserName(String username) 
        log.info("多个参数用  @ApiImplicitParams");
        return ApiResponse.<User>builder().code(200)
                .message("操作成功")
                .data(new User(1, username, "JAVA"))
                .build();
    

    @GetMapping("/id")
    @ApiOperation(value = "主键查询（DONE）", notes = "备注")
    @ApiImplicitParams(@ApiImplicitParam(name = "id", value = "用户编号", dataType = DataType.INT, paramType = ParamType.PATH))
    public ApiResponse<User> get(@PathVariable Integer id) 
        log.info("单个参数用  @ApiImplicitParam");
        return ApiResponse.<User>builder().code(200)
                .message("操作成功")
                .data(new User(id, "u1", "p1"))
                .build();
    
    @DeleteMapping("/id")
    @ApiOperation(value = "删除用户（DONE）", notes = "备注")
    @ApiImplicitParam(name = "id", value = "用户编号", dataType = DataType.INT, paramType = ParamType.PATH)
    public void delete(@PathVariable Integer id) 
        log.info("单个参数用 ApiImplicitParam");
    
    @PostMapping
    @ApiOperation(value = "添加用户（DONE）")
    public User post(@RequestBody User user) 
        log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam");
        return user;
    
    @PostMapping("/multipar")
    @ApiOperation(value = "添加用户（DONE）")
    public List<User> multipar(@RequestBody List<User> user) 
        log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam");
        return user;
    
    @PostMapping("/array")
    @ApiOperation(value = "添加用户（DONE）")
    public User[] array(@RequestBody User[] user) 
        log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam");
        return user;
    
    @PutMapping("/id")
    @ApiOperation(value = "修改用户（DONE）")
    public void put(@PathVariable Long id, @RequestBody User user) 
        log.info("如果你不想写 @ApiImplicitParam 那么 swagger 也会使用默认的参数名作为描述信息 ");
    
    @PostMapping("/id/file")
    @ApiOperation(value = "文件上传（DONE）")
    public String file(@PathVariable Long id, @RequestParam("file") MultipartFile file) 
        log.info(file.getContentType());
        log.info(file.getName());
        log.info(file.getOriginalFilename());
        return file.getOriginalFilename();

ApiResponse.java

主要演示了实体类的注解。

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "通用PI接口返回", description = "Common Api Response")
public class ApiResponse<T> implements Serializable 
    private static final long serialVersionUID = -8987146499044811408L;

    @ApiModelProperty(value = "通用返回状态", required = true)
    private Integer code;

    @ApiModelProperty(value = "通用返回信息", required = true)
    private String message;

    @ApiModelProperty(value = "通用返回数据", required = true)
    private T data;

参考

swagger 官方网站：https://swagger.io/
swagger 官方文档：https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X—Getting-started
swagger 常用注解：https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X—Annotations

spring-boot-demo-swagger-beauty

(https://github.com/battcn/swagger-spring-boot) 集成。
启动项目，访问地址：http://localhost:8080/demo/swagger-ui.html#/
用户名：xkcoding
密码：123456

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <artifactId>spring-boot-demo-swagger-beauty</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>jar</packaging>
    <parent>
        <groupId>com.xkcoding</groupId>
        <artifactId>spring-boot-demo</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
        <battcn.swagger.version>2.1.2-RELEASE</battcn.swagger.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>com.battcn</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>$battcn.swagger.version</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>
    <build>
        <finalName>spring-boot-demo-swagger-beauty</finalName>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

application.yml

server:
  port: 8080
  servlet:
    context-path: /demo
spring:
  swagger:
    enabled: true
    title: spring-boot-demo
    description: 这是一个简单的 Swagger API 演示
    version: 1.0.0-SNAPSHOT
    contact:
      name: Yangkai.Shen
      email: 237497819@qq.com
      url: http://xkcoding.com
    # swagger扫描的基础包，默认：全扫描
    # base-package:
    # 需要处理的基础URL规则，默认：/**
    # base-path:
    # 需要排除的URL规则，默认：空
    # exclude-path:
    security:
      # 是否启用 swagger 登录验证
      filter-plugin: true
      username: xkcoding
      password: 123456
    global-response-messages:
      GET[0]:
        code: 400
        message: Bad Request，一般为请求参数不对
      GET[1]:
        code: 404
        message: NOT FOUND，一般为请求路径不对
      GET[2]:
        code: 500
        message: ERROR，一般为程序内部错误
      POST[0]:
        code: 400
        message: Bad Request，一般为请求参数不对
      POST[1]:
        code: 404
        message: NOT FOUND，一般为请求路径不对
      POST[2]:
        code: 500
        message: ERROR，一般为程序内部错误

ApiResponse.java

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "通用PI接口返回", description = "Common Api Response")
public class ApiResponse<T> implements Serializable 
    private static final long serialVersionUID = -8987146499044811408L;
    @ApiModelProperty(value = "通用返回状态", required = true)
    private Integer code;
    @ApiModelProperty(value = "通用返回信息", required = true)
    private String message;
    @ApiModelProperty(value = "通用返回数据", required = true)
    private https://github.com/AmberBar/Learning/tree/master/swagger-learning/swagger
需要的小伙伴可以clone直接运行
访问地址
http://localhost:9999/swagger-ui.html#/