一、OpenAPI工具

OpenAPI.Tools

• OpenApi 文档编辑器，推荐使用：Stoplight Studio
• Mock服务器，推荐使用Prism
• 代码生成工具：OpenAPI Generator，github

二、OpenAPI文档

Open API Specification

• 文档可以使用yaml或者json描述
• Open API规范的内容：路径，http操作；基本信息；联系方式；授权路径；访问控制；服务器
• OpenAPI文档实际上就是HTTP操作描述的集合
• 设计API的过程就是编写OpenAPI文档的过程，后续的开发工作会基于这个OpenAPI文档进行
• 建议使用Stoplight studio创建的OpenAPI文档

Stoplight

• Stoplight studio，集成IDE
• Spectral，验证
• Prism，模拟服务器

eg：Stoplight studio创建一个支付的OpenAPI文档

（1）设置一些基本信息

（2）创建一个路径用于查询支付状态

使用（3）中创建的Response在这里使用这个Response

（3）创建一个Response

（4）创建一个路径用于创建支付记录

保存项目工程

工程最终就是一个yaml文件

openapi: 3.1.0

# ASAM SOVD V1.0.0

# © by ASAM e.V., 2022

# SOVD API Fault Data Types
# This file is informative. The normative REST API definition is published in the specification.


# Any use is limited to the scope described in the ASAM license terms.
# See http://www.asam.net/license.html  for further details.

info:
  title: SOVD API Fault Data Types
  license:
    name: Licensing Terms for Grant of Rights to Use ASAM Products
    url: https://www.asam.net/license/
  version: 1.0.0
  description: >-
    Data types for representing faults

paths: {}

components:
  # ==========================================================================
  # Schema definitions
  schemas:
    # ------------------------------------------------------------------------
    # Schema: ListOfFaults
    ListOfFaults:
      description: >-
        List of all faults of a device
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Fault'
        schema:
          description: >-
            Schema for describing the fault response.
            Condition: Only provided if the query parameter include-schema is true.
          $ref: ../commons/types.yaml#/components/schemas/OpenApiSchema

    # ------------------------------------------------------------------------
    # Schema: Fault
    Fault:
      description: >-
        Description of a single fault
      type: object
      required:
        - code
        - fault_name
      properties:
        code:
          description: >-
            Fault code in the native representation of the entity.
          type: string
          example: '0012E3'
        scope:
          description: >-
            Defines the scope (e.g., user-defined fault memories) for fault entries.
            The capability description defines which scopes are supported.
          type: string
          example: Default
        display_code:
          description: >-
            Display representation for the fault code.
          type: string
          example: P102
        fault_name:
          description: >-
            Name / description of the fault
          type: string
          example: No signal from sensor
        fault_translation_id:
          description: >-
            Optional identifier for translating the name
          type: string
          example: CAMERA_0012E3_tid
        severity:
          description: >-
            Severity defines the impact on the availability of the vehicle. Lower number means higher severity.
            For a classic ECU this resembles the level from ODX, for HPCs the SOVD API recommends
            1 = FATAL,
            2 = ERROR,
            3 = WARN, and
            4 = INFO.
          type: integer
          example: 1
        status:
          description:
            Detailed status information for the fault as key value pairs. For classic ECU this resembles the status byte of a DTC.
            The content of the keys and values is OEM-specific. The keys are defined in the capability description. See Notes below.
          type: object
        symptom:
          description: >-
            Detailed symptom / failure mode information for the fault. For classic ECU this resembles the symptom of a DTC.
            The content of the attribute is OEM-specific.
          type: string
        symptom_transaction_id:
          description: >-
            Translation identifier for the symptom name.
          type: string
          items:
            $ref: ../commons/types.yaml#/components/schemas/AnyValue

四、OpenAPI Generator

功能：

• 根据OpenAPI文档生成不同类型的代码，支持生成多种编程语言和框架

使用方式：

• 使用命令行工具，以jar包的形式提供

子命令：
generator

查看generator的帮助
openapi-generator-cli help generator
重要参数：
-g:指定生成器
-i：输入的openAPI文档
-o：指定代码生成目录
-p: 传递生成器特有的配置项



=======================================================
辅助命令：
验证OpenAPI文档
openapi-generator-cli validate -i payment-service.yaml

列出生成器：客户端，服务器端，文档，模式，配置生成器
openapi-genertor-cli list

查看生成器的配置项
openapi-generator-cli config-help -g spring

eg：生成使用Spring的服务器端代码

openapi-generator-cli generate -g spring -i payment-service.yaml -o payment-service-server-spring
openapi-generator-cli generate -g spring -i payment-service.yaml -o payment-service-server-spring -p delegatePattern=true

• 使用Maven或者Gradle的插件
• 使用在线服务，发送代码生成请求到公开或者私有的服务器上，然后下载生成好的代码（使用较少），openapi-generator online

五、API规范(契约)

（1）API规范就是契约契约。

Reset API的规范可以使用OpenAPI规范或者早期的Swagger；

• Open API规范基于Swagger发展而来，以yaml或者json的格式来表述RESET API的契约
• Open API规范中最重要的两个元素：路径，模型
  （1）路径是标识每个API的访问路径，可以定义路径的参数、查询参数、请求格式和相应格式等
  （2）模型是定义请求和响应中可能出现的对象的结构
  （3）OpenAPI的时候是Json或者yaml的

gRPC API使用Protobuf来定义API契约；

（2）查看OpenAPI生成的文件，可以使用swagger UI

docker run --rm -p 8800:8080 -v /home/wangji/test.yaml:/openapi.yaml -e SWAGGER_JSON_=/openapi.yml/swaggerapi/swagger-ui 

打开浏览器即可：

（3）模拟服务器

• 可以使用Stoplight Prism

prism-cli  mock -d product.v1.yaml

服务器默认端口：4010
-d：标识给出随机数据

（4）OpenAPI Generator可以生成访问API的客户端和服务器端代码

eg：使用yaml生成java代码

（1）下载OpenAPI Generator CLI的jar文件
（2）执行命令:
生成客户端代码：
java -jar ./openapi-generator-cli-5.0.0-beta2.jar generate -i ./product.v1.yaml -g java -o product-java-client
生成服务端代码，使用spring框架生成服务端代码
java -jar ./openapi-generator-cli-5.0.0-beta2.jar generate -i ./product.v1.yaml -g spring -o product-java-server

使用IDEA打开创建的服务端代码，生成的代码中内置了Swagger UI，直接启动服务端，输入：localhost: 3000即可

参考

• 【API 优先的设计】工具篇