SpringBoot2.x 集成 Swagger3

最新推荐文章于 2024-09-04 21:59:45 发布
置顶 最新推荐文章于 2024-09-04 21:59:45 发布
阅读量1.4k 收藏 2
点赞数 2
分类专栏： SpringBoot 文章标签： spring boot swagger3 springfox swagger3分组配置 knife4j
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/RtxTitanV/article/details/117908735
版权

Swagger是一款RESTFUL接口的文档在线自动生成加功能测试的软件，提供描述、生产、消费和可视化RESTful Web Service。Swagger也是一个api文档维护组织，后来成为了OpenAPI（一个业界的api文档标准）标准的主要定义者，现在最新的版本为17年发布的Swagger3（OpenAPI3）。基于OpenAPI2的Swagger2已于2017年停止维护。

SpringFox是Spring社区维护的一个项目（非官方），帮助使用者将Swagger2集成到Spring中。常用于Spring中帮助开发者生成文档，并可以轻松的在SpringBoot中使用，目前已经支持OpenAPI3标准。

本文主要对SpringBoot2.x集成Swagger3进行简单总结，通过引入SpringFox来使用Swagger3，其中SpringBoot使用的2.4.5版本。

一、引入依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<!-- lombok插件 -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.8</version>
</dependency>

二、编写配置类

package com.rtxtitanv.config;

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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.Collections;

/**
 * @author rtxtitanv
 * @version 1.0.0
 * @name com.rtxtitanv.config.Swagger3Config
 * @description Swagger3配置类
 * @date 2021/6/7 12:47
 */
@Configuration
@EnableOpenApi
public class Swagger3Config {

    /**
     * 配置默认分组
     *
     * @return springfox.documentation.spring.web.plugins.Docket
     */
    @Bean
    public Docket defaultApi() {
        // DocumentationType.OAS_30为Swagger3的文档类型
        return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).select()
            /*
             * 通过apis和paths方法设置ApiSelector的构建规则
             * ApiSelectorBuilder apis(Predicate<RequestHandler> selector)
             *     RequestHandlerSelectors.any()：构建所有API
             *     RequestHandlerSelectors.none()：所有API都不构建
             *     RequestHandlerSelectors.basePackage()：构建指定包路径下的所有API
             *     RequestHandlerSelectors.withClassAnnotation()：仅构建带有指定类注解的API
             *     RequestHandlerSelectors.withMethodAnnotation()：仅构建带有指定方法注解的API
             * ApiSelectorBuilder paths(Predicate<String> selector)
             *     PathSelectors.any()：构建所有请求路径的API
             *     PathSelectors.none()：所有请求路径的API都不构建
             *     PathSelectors.regex()：仅构建正则匹配的请求路径的API
             *     PathSelectors.ant()：仅构建与ant模式匹配的API
             */
            .apis(RequestHandlerSelectors.basePackage("com.rtxtitanv.controller.other")).paths(PathSelectors.any())
            .build();
    }

    /**
     * 配置user分组
     *
     * @return springfox.documentation.spring.web.plugins.Docket
     */
    @Bean
    public Docket userApi() {
        return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
            // 通过securitySchemes和securityReferences方法进行JWT配置
            .securitySchemes(Collections.singletonList(HttpAuthenticationScheme.JWT_BEARER_BUILDER.name("JWT").build()))
            .securityContexts(Collections.singletonList(SecurityContext.builder()
                .securityReferences(Collections.singletonList(
                    SecurityReference.builder().scopes(new AuthorizationScope[0]).reference("JWT").build()))
                .operationSelector(operationContext -> operationContext.requestMappingPattern().matches("/.*"))
                .build()))
            .select().apis(RequestHandlerSelectors.basePackage("com.rtxtitanv.controller.user"))
            // groupName方法设置分组名称
            .paths(PathSelectors.regex("/user/.*")).build().groupName("user");
    }

    /**
     * 配置order分组
     *
     * @return springfox.documentation.spring.web.plugins.Docket
     */
    @Bean
    public Docket orderApi() {
        return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
            .securitySchemes(Collections.singletonList(HttpAuthenticationScheme.JWT_BEARER_BUILDER.name("JWT").build()))
            .securityContexts(Collections.singletonList(SecurityContext.builder()
                .securityReferences(Collections.singletonList(
                    SecurityReference.builder().scopes(new AuthorizationScope[0]).reference("JWT").build()))
                .operationSelector(operationContext -> operationContext.requestMappingPattern().matches("/.*"))
                .build()))
            .select().apis(RequestHandlerSelectors.basePackage("com.rtxtitanv.controller.order"))
            .paths(PathSelectors.regex("/order/.*")).build().groupName("order");
    }

    /**
     * 构建API文档基本信息
     *
     * @return springfox.documentation.service.ApiInfo
     */
    private ApiInfo apiInfo() {
        // 联系人信息：分别为作者、主页、邮箱
        Contact contact = new Contact("RtxTitanV", "https://blog.csdn.net/RtxTitanV", "RtxTitanV@xxx.com");
        // 构建API文档的详细信息：依次为API标题、API描述、API联系人信息、API版本、API许可、API许可Url
        return new ApiInfoBuilder().title("SpringBoot2.x 集成 Swagger3").description("SpringBoot2.x 集成 Swagger3 测试文档")
            .contact(contact).version("1.0.0").license("Apache 2.0")
            .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0").build();
    }
}

配置类中每一个Docket对象都代表一个分组，Bean的名称不能相同，通过调用groupName(String groupName)方法来设置分组名。以上配置了三个分组，分别为default、user、order三组，其中没有调用groupName(String groupName)的Docket对象是默认分组配置，不同的分组可以配置不同的API文档基本信息（文档标题、描述、联系人信息等），这里主要是测试，就都配置的统一的API文档基本信息。另外user和order分组都配置了JWT认证，配置方式与Swagger2有所不同，配置JWT认证后在API文档中认证了Token之后，每次请求时在请求头都会携带该token。

Doket类的方法Docket enable(boolean externallyConfiguredFlag)可以控制Swagger的开启和关闭，可以根据不同环境进行动态的配置。配置项springfox.documentation.enabled也可以控制Swagger的开启与关闭，设置为false可以关闭Swagger。

三、创建实体类

package com.rtxtitanv.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;

import java.io.Serializable;

/**
 * @author rtxtitanv
 * @version 1.0.0
 * @name com.rtxtitanv.model.User
 * @description 用户实体类
 * @date 2021/6/7 12:41
 */
@Accessors(chain = true)
@AllArgsConstructor
@NoArgsConstructor
@Data
@ApiModel(value = "User", description = "用户信息")
public class User implements Serializable {

    private static final long serialVersionUID = -583023130164283193L;
    @ApiModelProperty(value = "用户id")
    private Long id;
    @ApiModelProperty(value = "用户名")
    private String username;
    @ApiModelProperty(value = "密码")
    private String password;
}

package com.rtxtitanv.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;

import java.io.Serializable;

/**
 * @author rtxtitanv
 * @version 1.0.0
 * @name com.rtxtitanv.model.Order
 * @description 订单实体类
 * @date 2021/6/8 11:30
 */
@Accessors(chain = true)
@AllArgsConstructor
@NoArgsConstructor
@Data
@ApiModel(value = "Order", description = "订单信息")
public class Order implements Serializable {

    private static final long serialVersionUID = -688022729580581140L;
    @ApiModelProperty(value = "订单id")
    private Long id;
    @ApiModelProperty(value = "订单编号")
    private String orderNumber;
    @ApiModelProperty(value = "订单描述")
    private String orderDescription;
    @ApiModelProperty(value = "订单所属用户id")
    private Long userId;
}

package com.rtxtitanv.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.http.HttpStatus;

import java.io.Serializable;

/**
 * @author rtxtitanv
 * @version 1.0.0
 * @name com.rtxtitanv.model.CommonResult
 * @description 通用响应类
 * @date 2021/6/8 10:45
 */
@AllArgsConstructor
@NoArgsConstructor
@Data
@ApiModel(value = "CommonResult", description = "通用响应对象")
public class CommonResult<T> implements Serializable {

    private static final long serialVersionUID = 2622902426607852032L;
    @ApiModelProperty(value = "响应码", required = true)
    private int code;
    @ApiModelProperty(value = "响应信息", required = true)
    private String message;
    @ApiModelProperty(value = "响应数据")
    private T data;

    public static <T> CommonResult<T> success(String message, T data) {
        return new CommonResult<>(HttpStatus.OK.value(), message, data);
    }

    public static <T> CommonResult<T> invalidParameter(String message) {
        return new CommonResult<>(HttpStatus.BAD_REQUEST.value(), message, null);
    }

    public static <T> CommonResult<T> notFound(String message) {
        return new CommonResult<>(HttpStatus.NOT_FOUND.value(), message, null);
    }
}

四、Controller层

分组default中的用于简单测试的Controller：

package com.rtxtitanv.controller.other;

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

/**
 * @author rtxtitanv
 * @version 1.0.0
 * @name com.rtxtitanv.controller.other.TestController
 * @description TestController
 * @date 2021/6/7 12:47
 */
@Api(value = "TestController", tags = "简单测试", description = "用于简单测试的API")
@RequestMapping("/test")
@RestController
public class TestController {

    @ApiOperation(value = "hello", notes = "一个简单的测试接口")
    @ApiImplicitParam(value = "名称", name = "name", required = true, defaultValue = "world",
        dataTypeClass = String.class)
    @GetMapping("/hello/{name}")
    public String hello(@PathVariable(value = "name") String name) {
        return "hello " + name;
    }
}

分组user中的Controller：

package com.rtxtitanv.controller.user;

import com.rtxtitanv.model.CommonResult;
import com.rtxtitanv.model.User;
import com.rtxtitanv.service.UserService;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

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

/**
 * @author rtxtitanv
 * @version 1.0.0
 * @name com.rtxtitanv.controller.user.UserController
 * @description UserController
 * @date 2021/6/7 12:47
 */
@Api(value = "用户模块", tags = "用户管理", description = "用户的增删改查", protocols = "http")
@RequestMapping("/user")
@RestController
public class UserController {

    @Resource
    private UserService userService;

    @ApiOperation(value = "创建用户", notes = "根据User对象保存用户")
    @ApiImplicitParams(value = {
        @ApiImplicitParam(value = "用户id", name = "id", required = true, defaultValue = "1", dataTypeClass = Long.class,
            paramType = "query"),
        @ApiImplicitParam(value = "用户名", name = "username", required = true, defaultValue = "admin",
            dataTypeClass = String.class, paramType = "query"),
        @ApiImplicitParam(value = "密码", name = "password", required = true, defaultValue = "admin",
            dataTypeClass = String.class, paramType = "query")})
    @ApiResponses(value = {@ApiResponse(code = 200, message = "保存用户成功"),
        @ApiResponse(code = 400, message = "无效参数", response = CommonResult.class)})
    @PostMapping("/save")
    public CommonResult<User> saveUser(@ApiIgnore User user) {
        return userService.saveUser(user);
    }

    @ApiOperation(value = "查询所有用户", notes = "查询所有用户")
    @ApiResponses(value = {@ApiResponse(code = 200, message = "查询所有用户成功")})
    @GetMapping("/findAll")
    public CommonResult<List<User>> findUserAll() {
        return userService.findUserAll();
    }

    @ApiOperation(value = "根据id查询用户", notes = "查询指定id用户")
    @ApiImplicitParam(value = "用户id", name = "id", required = true, defaultValue = "1", dataTypeClass = Long.class)
    @ApiResponses(value = {@ApiResponse(code = 200, message = "根据id查询用户成功"),
        @ApiResponse(code = 400, message = "无效参数", response = CommonResult.class)})
    @GetMapping("/findById/{id}")
    public CommonResult<User> findUserById(@PathVariable(value = "id") Long id) {
        return userService.findUserById(id);
    }

    @ApiOperation(value = "根据id更新用户", notes = "更新指定id用户")
    @ApiResponses(value = {@ApiResponse(code = 200, message = "根据id更新用户成功"),
        @ApiResponse(code = 400, message = "无效参数", response = CommonResult.class),
        @ApiResponse(code = 404, message = "用户不存在", response = CommonResult.class)})
    @PutMapping("/updateById")
    public CommonResult<User> updateUserById(@RequestBody User user) {
        return userService.updateUserById(user);
    }

    @ApiOperation(value = "根据id删除用户", notes = "删除指定id用户")
    @ApiImplicitParam(value = "用户id", name = "id", required = true, defaultValue = "1", dataTypeClass = Long.class)
    @ApiResponses(value = {@ApiResponse(code = 200, message = "根据id删除用户成功"),
        @ApiResponse(code = 400, message = "无效参数", response = CommonResult.class),
        @ApiResponse(code = 404, message = "用户不存在", response = CommonResult.class)})
    @DeleteMapping("/deleteById/{id}")
    public CommonResult<User> deleteUserById(@PathVariable(value = "id") Long id) {
        return userService.deleteUserById(id);
    }

    @ApiOperation(value = "删除所有用户", notes = "删除所有用户")
    @ApiResponses(value = {@ApiResponse(code = 200, message = "删除所有用户成功"),
        @ApiResponse(code = 404, message = "用户不存在", response = CommonResult.class)})
    @DeleteMapping("/deleteAll")
    public CommonResult<List<User>> deleteUserAll() {
        return userService.deleteUserAll();
    }
}

分组order中的Controller：

package com.rtxtitanv.controller.order;

import com.rtxtitanv.model.CommonResult;
import com.rtxtitanv.model.Order;
import com.rtxtitanv.service.OrderService;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

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

/**
 * @author rtxtitanv
 * @version 1.0.0
 * @name com.rtxtitanv.controller.order.OrderController
 * @description OrderController
 * @date 2021/6/8 11:31
 */
@Api(value = "订单模块", tags = "订单管理", description = "订单的增删改查", protocols = "http")
@RequestMapping("/order")
@RestController
public class OrderController {

    @Resource
    private OrderService orderService;

    @ApiOperation(value = "创建订单", notes = "根据Order对象保存订单")
    @ApiImplicitParams(value = {
        @ApiImplicitParam(value = "订单id", name = "id", required = true, defaultValue = "1", dataTypeClass = Long.class,
            paramType = "query"),
        @ApiImplicitParam(value = "订单编号", name = "orderNumber", required = true, defaultValue = "780829537365759918",
            dataTypeClass = String.class, paramType = "query"),
        @ApiImplicitParam(value = "订单描述", name = "orderDescription", required = true, defaultValue = "二两牛肉面，微辣，多放点香菜",
            dataTypeClass = String.class, paramType = "query"),
        @ApiImplicitParam(value = "订单所属用户id", name = "userId", required = true, defaultValue = "1",
            dataTypeClass = Long.class, paramType = "query")})
    @ApiResponses(value = {@ApiResponse(code = 200, message = "保存订单成功"),
        @ApiResponse(code = 400, message = "无效参数", response = CommonResult.class)})
    @PostMapping("/save")
    public CommonResult<Order> saveOrder(@ApiIgnore Order order) {
        return orderService.saveOrder(order);
    }

    @ApiOperation(value = "查询所有订单", notes = "查询所有订单")
    @ApiResponses(value = {@ApiResponse(code = 200, message = "查询所有订单成功")})
    @GetMapping("/finAll")
    public CommonResult<List<Order>> findOrderAll() {
        return orderService.findOrderAll();
    }

    @ApiOperation(value = "根据id更新订单", notes = "更新指定id订单")
    @ApiResponses(value = {@ApiResponse(code = 200, message = "根据id更新订单成功"),
        @ApiResponse(code = 400, message = "无效参数", response = CommonResult.class),
        @ApiResponse(code = 404, message = "订单不存在", response = CommonResult.class)})
    @PutMapping("/updateById")
    public CommonResult<Order> updateOrderById(@RequestBody Order order) {
        return orderService.updateOrderById(order);
    }

    @ApiOperation(value = "根据id删除订单", notes = "删除指定id订单")
    @ApiImplicitParam(value = "订单id", name = "id", required = true, defaultValue = "1", dataTypeClass = Long.class)
    @ApiResponses(value = {@ApiResponse(code = 200, message = "根据id删除订单成功"),
        @ApiResponse(code = 400, message = "无效参数", response = CommonResult.class),
        @ApiResponse(code = 404, message = "订单不存在", response = CommonResult.class)})
    @DeleteMapping("/deleteById/{id}")
    public CommonResult<Order> deleteOrderById(@PathVariable(value = "id") Long id) {
        return orderService.deleteOrderById(id);
    }
}

这里仍然使用的Swagger的文档注解，是因为Swagger3（OpenAPI3）的@Tag注解有点问题没有生效，在Swagger-UI上，Controller上@Tag的name属性表示的Controller的标题在和增删改查接口是分开的，并没有在同一个折叠面板中，所以还是换回了Swagger2的注解。

五、Service层

package com.rtxtitanv.service;

import com.rtxtitanv.model.CommonResult;
import com.rtxtitanv.model.User;

import java.util.List;

/**
 * @author rtxtitanv
 * @version 1.0.0
 * @name com.rtxtitanv.service.UserService
 * @description UserService
 * @date 2021/6/7 12:48
 */
public interface UserService {

    /**
     * 保存用户
     *
     * @param user 用户参数
     * @return CommonResult<User>
     */
    CommonResult<User> saveUser(User user);

    /**
     * 查询所有用户
     *
     * @return CommonResult<List<User>>
     */
    CommonResult<List<User>> findUserAll();

    /**
     * 根据id查询用户
     *
     * @param id 用户id
     * @return CommonResult<User>
     */
    CommonResult<User> findUserById(Long id);

    /**
     * 根据id更新用户
     *
     * @param user 用户参数
     * @return CommonResult<User>
     */
    CommonResult<User> updateUserById(User user);

    /**
     * 根据id删除用户
     *
     * @param id 用户id
     * @return CommonResult<User>
     */
    CommonResult<User> deleteUserById(Long id);

    /**
     * 删除所有用户
     *
     * @return CommonResult<List<User>>
     */
    CommonResult<List<User>> deleteUserAll();
}

package com.rtxtitanv.service.impl;

import com.rtxtitanv.exception.InvalidParameterException;
import com.rtxtitanv.exception.NotFoundException;
import com.rtxtitanv.model.CommonResult;
import com.rtxtitanv.model.User;
import com.rtxtitanv.service.UserService;
import org.springframework.stereotype.Service;

import java.util.*;

/**
 * @author rtxtitanv
 * @version 1.0.0
 * @name com.rtxtitanv.service.impl.UserServiceImpl
 * @description UserService实现类
 * @date 2021/6/7 12:49
 */
@Service
public class UserServiceImpl implements UserService {

    /**
     * 创建线程安全的Map，模拟用户信息的存储
     */
    private static final Map<Long, User> USER_MAP = Collections.synchronizedMap(new HashMap<>());

    @Override
    public CommonResult<User> saveUser(User user) {
        if (user.getId() <= 0) {
            throw new InvalidParameterException("无效参数");
        }
        USER_MAP.put(user.getId(), user);
        return CommonResult.success("保存用户成功", user);
    }

    @Override
    public CommonResult<List<User>> findUserAll() {
        return CommonResult.success("查询所有用户成功", new ArrayList<>(USER_MAP.values()));
    }

    @Override
    public CommonResult<User> findUserById(Long id) {
        if (id <= 0) {
            throw new InvalidParameterException("无效参数");
        }
        return CommonResult.success("根据id查询用户成功", USER_MAP.get(id));
    }

    @Override
    public CommonResult<User> updateUserById(User user) {
        if (user.getId() <= 0) {
            throw new InvalidParameterException("无效参数");
        }
        if (USER_MAP.get(user.getId()) == null) {
            throw new NotFoundException("用户不存在");
        }
        user = USER_MAP.get(user.getId()).setUsername(user.getUsername()).setPassword(user.getPassword());
        return CommonResult.success("根据id更新用户成功", user);
    }

    @Override
    public CommonResult<User> deleteUserById(Long id) {
        if (id <= 0) {
            throw new InvalidParameterException("无效参数");
        }
        if (USER_MAP.get(id) == null) {
            throw new NotFoundException("用户不存在");
        }
        return CommonResult.success("根据id删除用户成功", USER_MAP.remove(id));
    }

    @Override
    public CommonResult<List<User>> deleteUserAll() {
        if (USER_MAP.isEmpty()) {
            throw new NotFoundException("用户不存在");
        }
        ArrayList<User> users = new ArrayList<>(USER_MAP.values());
        USER_MAP.clear();
        return CommonResult.success("删除所有用户成功", users);
    }
}

package com.rtxtitanv.service;

import com.rtxtitanv.model.CommonResult;
import com.rtxtitanv.model.Order;

import java.util.List;

/**
 * @author rtxtitanv
 * @version 1.0.0
 * @name com.rtxtitanv.service.OrderService
 * @description OrderService
 * @date 2021/6/8 17:18
 */
public interface OrderService {

    /**
     * 保存订单
     *
     * @param order 订单参数
     * @return CommonResult<Order>
     */
    CommonResult<Order> saveOrder(Order order);

    /**
     * 查询所有订单
     *
     * @return CommonResult<List<Order>>
     */
    CommonResult<List<Order>> findOrderAll();

    /**
     * 根据id更新订单
     *
     * @param order 订单参数
     * @return CommonResult<Order>
     */
    CommonResult<Order> updateOrderById(Order order);

    /**
     * 根据id删除订单
     *
     * @param id 订单id
     * @return CommonResult<Order>
     */
    CommonResult<Order> deleteOrderById(Long id);
}

package com.rtxtitanv.service.impl;

import com.rtxtitanv.exception.InvalidParameterException;
import com.rtxtitanv.exception.NotFoundException;
import com.rtxtitanv.model.CommonResult;
import com.rtxtitanv.model.Order;
import com.rtxtitanv.service.OrderService;
import org.springframework.stereotype.Service;

import java.util.*;

/**
 * @author rtxtitanv
 * @version 1.0.0
 * @name com.rtxtitanv.service.impl.OrderServiceImpl
 * @description OrderService实现类
 * @date 2021/6/8 17:18
 */
@Service
public class OrderServiceImpl implements OrderService {

    /**
     * 创建线程安全的Map，模拟订单信息的存储
     */
    private static final Map<Long, Order> ORDER_MAP = Collections.synchronizedMap(new HashMap<>());

    @Override
    public CommonResult<Order> saveOrder(Order order) {
        if (order.getId() <= 0) {
            throw new InvalidParameterException("无效参数");
        }
        ORDER_MAP.put(order.getId(), order);
        return CommonResult.success("保存订单成功", order);
    }

    @Override
    public CommonResult<List<Order>> findOrderAll() {
        return CommonResult.success("查询所有订单成功", new ArrayList<>(ORDER_MAP.values()));
    }

    @Override
    public CommonResult<Order> updateOrderById(Order order) {
        if (order.getId() <= 0) {
            throw new InvalidParameterException("无效参数");
        }
        if (ORDER_MAP.get(order.getId()) == null) {
            throw new NotFoundException("订单不存在");
        }
        order = ORDER_MAP.get(order.getId()).setOrderNumber(order.getOrderNumber())
            .setOrderDescription(order.getOrderDescription()).setUserId(order.getUserId());
        return CommonResult.success("根据id更新订单成功", order);
    }

    @Override
    public CommonResult<Order> deleteOrderById(Long id) {
        if (id <= 0) {
            throw new InvalidParameterException("无效参数");
        }
        if (ORDER_MAP.get(id) == null) {
            throw new NotFoundException("订单不存在");
        }
        return CommonResult.success("根据id删除订单成功", ORDER_MAP.remove(id));
    }
}

六、全局异常处理

自定义异常类：

package com.rtxtitanv.exception;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.EqualsAndHashCode;
import lombok.NoArgsConstructor;

import java.io.Serializable;

/**
 * @author rtxtitanv
 * @version 1.0.0
 * @name com.rtxtitanv.exception.InvalidParameterException
 * @description 自定义异常类，无效参数异常
 * @date 2021/6/8 18:56
 */
@EqualsAndHashCode(callSuper = true)
@AllArgsConstructor
@NoArgsConstructor
@Data
public class InvalidParameterException extends RuntimeException implements Serializable {

    private static final long serialVersionUID = 1987968660448772948L;
    private String message;
}

package com.rtxtitanv.exception;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.EqualsAndHashCode;
import lombok.NoArgsConstructor;

import java.io.Serializable;

/**
 * @author rtxtitanv
 * @version 1.0.0
 * @name com.rtxtitanv.exception.NotFoundException
 * @description 自定义异常类，数据不存在的异常
 * @date 2021/6/8 18:56
 */
@EqualsAndHashCode(callSuper = true)
@AllArgsConstructor
@NoArgsConstructor
@Data
public class NotFoundException extends RuntimeException implements Serializable {

    private static final long serialVersionUID = -7962596135697516276L;
    private String message;
}

全局异常处理类：

package com.rtxtitanv.handler;

import com.rtxtitanv.exception.InvalidParameterException;
import com.rtxtitanv.exception.NotFoundException;
import com.rtxtitanv.model.CommonResult;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;

/**
 * @author rtxtitanv
 * @version 1.0.0
 * @name com.rtxtitanv.handler.GlobalExceptionHandler
 * @description 全局异常处理类
 * @date 2021/6/8 18:56
 */
@RestControllerAdvice
public class GlobalExceptionHandler {

    private static final Logger LOGGER = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    @ExceptionHandler(InvalidParameterException.class)
    @ResponseStatus(code = HttpStatus.BAD_REQUEST)
    public CommonResult<Object> invalidParameterException(InvalidParameterException e) {
        String message = e.getMessage();
        LOGGER.error("异常信息：" + message, e);
        return CommonResult.invalidParameter(message);
    }

    @ExceptionHandler(NotFoundException.class)
    @ResponseStatus(code = HttpStatus.NOT_FOUND)
    public CommonResult<Object> notFoundException(NotFoundException e) {
        String message = e.getMessage();
        LOGGER.error("异常信息：" + message, e);
        return CommonResult.notFound(message);
    }
}

七、运行项目查看文档

启动SpringBoot项目，访问Swagger-UI的地址http://localhost:8080/swagger-ui/查看接口文档：
1
切换到user分组：
2
3
切换到order分组：
4
创建订单接口如下：
5
创建订单接口的响应信息如下：
6
更新订单接口如下：
7
订单管理API的Schema：
8

八、测试接口

可以在API文档中进行接口测试。首先测试创建订单接口以保存订单，与Swagger2不同，在配置了JWT安全认证之后，页面右侧多了个Authorize按钮，点击该按钮，输入Token认证后，每次请求都会将该Token加到Authorization请求头中来访问后台资源：
9
点击Try it out按钮，输入参数后点击Execute：
10
测试结果如下，可见保存成功：
11
在进行查询测试前再保存2个数据，然后测试查询所有订单：
12
测试根据id更新订单接口：
13
测试根据id删除订单接口：
14
下面测试抛出自定义异常的情况，测试根据id删除订单接口，输入一个无效id：
15
测试根据id更新订单接口，更新一个不存在的订单：
16

九、引入knife4j

Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。前身是swagger-bootstrap-ui。

首先引入依赖：

<!-- knife4j 起步依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

注意：knife4j的版本需要根据引入的springfox版本而定。如果底层依赖的springfox框架版本是2.9.2，knife4j的版本使用2.02.0.5。如果底层springfox框架版本升级至`2.10.5`，OpenAPI规范是v2，knife4j的版本使用2.0.6。如果底层依赖springfox框架版本升级至3.0.3，OpenAPI规范是v3，knife4j的版本使用3.0~。

重启SpringBoot项目，访问knife4j的地址http://localhost:8080/doc.html查看接口文档：
17

代码示例

RtxTitanV
关注
专栏目录
SpringBoot2.x系列教程（五十三）SpringBoot2.x集成swagger2配置权限认证参数Authorize
程序新视界
03-25 4640
在使用swagger2时，如果api接口需要token等权限认证内容，那么此时可以有两种方案进行解决：方案一，每个请求上面都添加对应token的key和value值。方案二：全局统一添加权限认证的token。 一般情况下token都存放在header中。 引入swagger2依赖 引入对应的swagger2依赖： <dependency> <groupId>io.s...
springboot2.x集成Swagger3
白不懂黑的静的专栏
12-10 1431
目的： 在写这篇记录时，swagger的最新版本到了3.0.0了，在进行集成时，没注意，还按照2.0的集成，走了一些弯路，这里特记录下。 环境： 一个已经搭建好的干净的springboot框架，这个框架中我集成了mybatis. 什么是swagger？ 　Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。 一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。 　当我们在后台的接口修改了后...
Springboot2 Swagger3 集成
Gblfy_Blog
09-21 1203
文章目录一、默认UI1. 版本尝鲜2. 导入依赖3. 配置Swagger4. Docket配置4.访问路径二、bootstrapUI2.1. 导入依赖2.2. 访问地址 一、默认UI 1. 版本尝鲜 Swagger3在Swagger2的基础上进行了部分升级， 使用和Swagger2没有多少区别。 一个重要的优化是依赖的引入，由之前的多个依赖变更为一个依赖，跟随springboot-starter风格，同时引入了新的开关注解 @EnableOpenApi 以代替@EnableSwagger2 。 因此，集成.
SpringBoot开发——整合Swagger
最新发布
bjzhang75的博客
09-04 819
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。它使得前后端分离开发更加方便，有利于团队协作。JDK支持：支持JDK 8及以上版本。Spring Boot支持：适用于Spring Boot 2.x及更早版本。JDK支持：最新版本要求JDK 11及以上。Spring Boot支持：专为Spring Boot 3.x设计。
SpringBoot2整合Swagger3
04-12 819
简介:Swagger是一款简单并且功能强大的API表达工具。我们可以通过Swagger生成的API得到接口的交互式文档。例如:没用swagger3之前，一般用postman来测试接口，并且出一份接口详细文档给到前端 这是很麻烦的事。但是现在Swagger3能帮我们很好的解决测试接口和接口文档这些事。Swagger作用：1将项目中所有的接口展现在页面上，这样后端程序员就不需要专门为前端使用者编写专门的接口文 档；2当接口更新之后，只需要修改代码中的 Swagger。
SpringBoot2集成swagger3
没有翅膀的我们，只是随便认为不能飞而已
01-10 1295
本文版本选择swagger最新版3 依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> 添加
基于SpringBoot 2.X整合Swagger2
SLy .的博客
03-27 568
基于SpringBoot 2.X整合Swagger2 说明：本文旨在整理基于SpringBoot 2.X整合Swagger2基础功能，如有问题请指出 一. 在pom.xml文件中引入Swagger2的依赖 <!-- Swagger2 --> <dependency> <groupId>io.springfo...
springboot2.x集成swagger的方法示例
08-26
"SpringBoot 2.x集成Swagger的方法示例" SpringBoot 2.x集成Swagger的方法示例是一个非常重要的知识点，对于开发人员来说，掌握这个知识点可以极大地提高开发效率和质量。本文将详细介绍SpringBoot 2.x集成Swagger...
Knife4j各版本集成SpringBoot 2.x 3.x版本demo示例
04-23
在本示例中，我们将探讨如何将Knife4j集成到Spring Boot 2.x和3.x版本中，以实现高效且美观的API文档生成。 首先，让我们了解Knife4j的基本概念。Knife4j是由xiaoymin开发的，它是Swagger UI的一个增强版，提供了更...
springboot3.x 和swagger3整合
AndyZhanh123的博客
03-20 1348
spring-boot 3.0 整合 swagger3
在Springboot项目中集成swagger2
qq_53679622的博客
04-13 688
Springboot集成swagger2接口测试文档
SpringBoot+Swagger3+log4j2
11-12
整合技术SpringBoot+Swagger3+log4j2 环境jdk1.8,idea,maven 默认地址:http://localhost:8080/swagger-ui/
SpringBoot2.X与Swagger3 整合
风吹淡了悲伤
04-30 501
由于在使用Swagger2过程中，出现如下错误！而一时之间又没法找从出处，故被迫升级处理bug… 主要是队友开发没有留意，挖坑… 引入Maven包 <!--MP依赖文件 基于3.x版本--> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId>
spring boot 集成swagger3
xplan5的博客
01-11 692
swagger3整合，spring boot2.6集成swagger
SpringBoot教程（十七） | SpringBoot集成Swagger系列（版本2、版本3）
qq_20236937的博客
07-27 1426
SpringBoot集成Swagger
springboot2自动生成接口文档，swagger3的使用
夕颜的博客
04-28 1255
Swagger介绍 基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源接口文档自动生成工具，可以让开发人员快速设计、构建、记录以及使用 Rest API Swagger 主要包含了以下三个部分： Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。 Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 Rest API。 S
SpringBoot2.X与Swagger2.X整合
风吹淡了悲伤
04-30 259
由于业务需要，减少开发维护API时间，便有了Swagger与SpringBoot的整合 引入Maven包 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <
springboot2.7.10集成swagger3.0
TuringZGJ的博客
03-29 1343
验证：localhost:{port}/{context-path}/swagger-ui/index.html。
springboot3.x 使用swagger
10-19
Spring Boot 3.x使用Swagger需要引入Swagger依赖并进行相关配置。引用中提到了使用SpringFox和SpringDoc两种库来实现Swagger的集成。其中，SpringFox是一个开源的API文档框架，可以将Swagger集成到Spring Boot应用程序中。而SpringDoc则是另一种接口文档解决方案，可以在Spring Boot 3.x中使用。在引入Swagger依赖后，需要进行相关注解的使用和配置信息类的准备。具体的使用方法可以参考引用中提供的参考链接。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

RtxTitanV

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值