SwaggerEditor@next: use more appropriate fixtures

[char0n]

Is your feature request related to a problem?

Our current fixtures that editor can load, are a little bit chaotic. Here is how it looks today:

Here is the examples of what some of the menu items load:

Load OpenAPI 3.0 fixture

openapi: 3.0.3
info:
  title: OAS 3.0.3 sample with multiple servers
  version: 0.1.0
servers:
  - url: http://testserver1.com
  - url: http://testserver2.com
paths:
  /test/:
    get:
      responses:
        '200':
          description: Successful Response

Load OpenAPI 2.0 fixture

swagger: '2.0'
info:
  title: OAS2 response examples
  version: 1.0.0
produces:
  - application/json
paths:
  /foo1:
    get:
      summary: Response without a schema
      responses:
        '200':
          description: Successful response
          examples:
            application/json:
              foo: custom value no schema update fail apple
  /foo2:
    get:
      summary: Response with schema
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/Foo'
          examples:
            application/json:
              foo: custom value changes ok
definitions:
  Foo:
    type: object
    properties:
      foo:
        type: string
        example: bar

Load OpenAPI 3.1 fixture

openapi: 3.1.0
info:
  title: deref
  version: 1.0.0
servers:
  - description: local
    url: http://localhost:8082/
paths:
  /a:
    get:
      operationId: aget
      parameters:
        - $ref: '#/components/parameters/userId'
    post:
      operationId: apost
  /b:
    get:
      operationId: bget
      parameters:
        - $ref: '#/components/parameters/userId'
    post:
      operationId: bpost
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/foo'
components:
  schemas:
    foo:
      type: string
    bar:
      $id: http://localhost:8082/
      type: string
  parameters:
    userId:
      $ref: '#/components/parameters/indirection1'
      description: override
    indirection1:
      $ref: '#/components/parameters/indirection2'
      summary: indirect summary
    indirection2:
      $ref: '#/components/parameters/userIdRef'
      summary: indirect summary
    userIdRef:
      name: userId
      in: query
      description: ID of the user
      required: true
    externalRef:
      $ref: ./ex.json#/externalParameter
      description: another ref

Describe the solution you'd like

I'd like to propose more sensible and expected fixtures. All fixtures will load in YAML format. Fixture will either be standard petstore one provided by OpenAPI or AsyncAPI initiative or our own SmartBear used one. @hkosova also proposed to amend the nomenclature - fixture - example and move under File menu into submenu (if possible) - I fully support this suggestion and incorporated into this proposal.

• File >
• <separator>
• Import URL
• Import File
• Load Example >
  • OpenAPI 3.1 Petstore
  • OpenAPI 3.0 Petstore
  • OpenAPI 2.0 Petstore
  • <separator>
  • AsyncAPI 2.5 Petstore
  • AsyncAPI 2.5 Streetlights
  • <separator>
  • API Design Systems

Describe alternatives you've considered

Leaving the status quo, but IMHO we don't provide very good fixtures.

[tim-lai]

@ponelat @char0n
The three fixtures within the first three separators are the "official" fixtures. The next group were dev fixtures (e.g. deref), with the possible exception of ADS (not sure on its maturity). My expectation is that we'd eventually only end up with "official" fixtures, and all others would be removed. Atm, it's the "official" OAS3.1 fixture that is missing entirely.

[hkosova]

In UI text, consider using "example" or a similar common word instead of "fixture".

If the menu component supports submenus / nested menus, I would suggest moving those items to the "File" menu:

File >
  Import URL
  Import File
  ---
  Load Example >
    OpenAPI 3.1 Petstore
    OpenAPI 3.0 Petstore
    OpenAPI 2.0 Petstore
    ---
    AsyncAPI 2.5 Petstore
    AsyncAPI 2.5 Streetlights
    ---
    API Design Systems
  ---
  ...

[char0n]

The three fixtures within the first three separators are the "official" fixtures. The next group were dev fixtures (e.g. deref), with the possible exception of ADS (not sure on its maturity). My expectation is that we'd eventually only end up with "official" fixtures, and all others would be removed

This issue is about making the move now, so that we use standard industry recognized fixtures.

with the possible exception of ADS (not sure on its maturity)

ADS has full support in ApiDOM and we also created renderer that can render it. It's currently the only implementation out there.

Atm, it's the "official" OAS3.1 fixture that is missing entirely.

There is no official OPAS 3.1 fixture. The plan is to construct one from OpenAPI 3.0

---

@hkosova fully agree, updating my proposal.

[ponelat]

To clean up the examples (fka fixtures) sounds good.
For the OAS 3.1 example, it would be great to highlight some 3.1 specifics, most likely the JSON Schema side of things. Let's consider that in its own thread (and possibly suggest it to OAI).

[char0n]

Linking OpenAPI issue I've created to track the OpenAPI 3.1.0 Petstore effort: OAI/learn.openapis.org#98

[char0n]

@hkosova #3743 contains the implementations as you suggested with the submenu. Feel free to review the PR

[char0n]

NOTE: I've constructed OpenAPI 3.1 example from 3.0 version. When OAI/learn.openapis.org#98 is processed, I'll update the OpenAPI 3.1 example in SwaggerEditor@next to reflect the official OpenAPI 3.1 Petstore one.

[char0n]

Creation of idiomatic OpenAPI 3.1 Petstore fixture has been deferred to #3744