第二十九章 订单系统接口

此博客用于个人学习，来源于网上，对知识点进行一个整理。

1. 订单系统接口：

1.1 Swagger-UI：

1）什么是 OpenAPI：

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、前后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。 前端和后端的唯一联系，变成了 API 接口；API 文档变成了前后端开发人员联系的纽带，变得越来越重要。

没有 API 文档工具之前，大家都是手写 API 文档的，在什么地方书写的都有，而且 API 文档没有统一规范和格式，每个公司都不一样。这无疑给开发带来了灾难。

OpenAPI 规范（OpenAPI Specification 简称 OAS）是 Linux 基金会的一个项目，试图通过定义一种用来描述 API 格式或 API 定义的语言，来规范 RESTful 服务开发过程。目前 V3.0 版本的 OpenAPI 规范已经发布并开源在 github 上 。

2）什么是 swagger：

OpenAPI 是一个编写 API 文档的规范，然而如果手动去编写 OpenAPI 规范的文档，是非常麻烦的。而 Swagger 就是一个实现了 OpenAPI 规范的工具集。

Swagger包含的工具集：

• Swagger编辑器： Swagger Editor 允许您在浏览器中编辑 YAML 中的 OpenAPI 规范并实时预览文档。
• Swagger UI： Swagger UI 是 HTML，Javascript 和 CSS 资产的集合，可以从符合 OAS 标准的 API 动态生成漂亮的文档。
• Swagger Codegen： 允许根据 OpenAPI 规范自动生成 API 客户端库（SDK 生成），服务器存根和文档。
• Swagger Parser： 用于解析来自 Java 的 OpenAPI 定义的独立库。
• Swagger Core： 与 Java 相关的库，用于创建，使用和使用 OpenAPI 定义。
• Swagger Inspector（免费）： API 测试工具，可让您验证您的 API 并从现有 API 生成 OpenAPI 定义。
• SwaggerHub（免费和商业）： API 设计和文档，为使用 OpenAPI 的团队构建。

1.2 入门案例：

SpringBoot 已经集成了 Swagger，使用简单注解即可生成 swagger 的 API 文档。

1）引入依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

2）编写配置：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
   
    @Bean
    public Docket api() {
   
        return new Docket(DocumentationType.SWAGGER_2)
                .host("http://order.leyou.com")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.leyou.order.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
   
        return new ApiInfoBuilder()
                .title("乐优商城订单系统")
                .description("乐优商城订单系统接口文档")
                .version("1.0")
                .build();
    }
}

3）接口声明：

在 controller 的每个 handler 上添加接口说明注解：

@RestController
@RequestMapping("order")
@Api("订单服务接口")
public class OrderController {
   

    @Autowired
    private OrderService orderService;

    @Autowired
    private PayHelper payHelper;

    /**
     * 创建订单
     *
     * @param order 订单对象
     * @return 订单编号
     */
    @PostMapping
    @ApiOperation(value = "创建订单接口，返回订单编号", notes = "创建订单")
    @ApiImplicitParam(name = "order", required = true, value = "订单的json对象,包含订单条目和物流信息")
    public ResponseEntity<Long> createOrder(