swagger - 带有外部引用验证的 OpenApi

Question

来自 Soap、XSD、WSDL 领域，我试图找到一种方法来重用使用 OpenApi v3 时定义的一些模式。

目录结构:



地址.yaml

openapi: 3.0.1
info:
  title: An include file to define an address
  version: 1.0.0
paths: {}
components:
  schemas:
    Address:
      type: object
      properties:
        id:
          type: integer
          format: int64
        streetName:
          type: string
        streetNumber:
          type: integer
          format: int32
        city:
          type: string
        postalCode:
          type: string
          format: date-time
        country:
          type: string
          description: Allowed countries (just on purpose 3 to have an enum)
          enum:
            - Romania
            - Belgium
            - Hungary  

客户.yaml

   openapi: 3.0.1
info:
  title: An include file to define an customer
  version: 1.0.0
paths: {}
components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        address: $ref: './Address.yaml/#/components/schemas/Address'
    Customers:
        type: array
        items: $ref: '#/components/schemas/Customer'

CustomerApi.yaml

   openapi: 3.0.1
info:
  title: Sample API
  description: API description in Markdown.
  version: 1.0.0
servers:
  - url: 'https://api.example.com'
paths:
  /customers:
    get:
      summary: Returns a list of customers.
      description: will return all customers
      responses:
        '200':
          description: A list of customers.
          content:
            application/json:
              schema:
                $ref: '../models/Customer.yaml/#/components/schemas/Customers'

如何将这种结构与现有工具一起使用来验证和生成 Customer API 的 Java 代码？

谢谢

Answer 1

验证工具:

https://github.com/IBM/openapi-validator

npm install -g @apidevtools/swagger-cli
swagger-cli validate CustomerApi.yaml

https://github.com/APIDevTools/swagger-cli

npm install -g ibm-openapi-validator
lint-openapi CustomerApi.yaml

他们进行包括引用在内的验证。一旦 OpenAPI 有效，您将能够使用其他工具生成代码