Skip to content

SwaggerEditor@next: use more appropriate fixtures #3627

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
char0n opened this issue Nov 8, 2022 · 8 comments
Closed

SwaggerEditor@next: use more appropriate fixtures #3627

char0n opened this issue Nov 8, 2022 · 8 comments

Comments

@char0n
Copy link
Member

char0n commented Nov 8, 2022

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:

image

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
Copy link
Contributor

tim-lai commented Nov 8, 2022

@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
Copy link
Contributor

hkosova commented Nov 8, 2022

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
Copy link
Member Author

char0n commented Nov 9, 2022

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
Copy link
Contributor

ponelat commented Nov 9, 2022

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
Copy link
Member Author

char0n commented Nov 9, 2022

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

char0n added a commit that referenced this issue Dec 22, 2022
Examples now don't contain any dev related fixtures.

Refs #3627
@char0n
Copy link
Member Author

char0n commented Dec 22, 2022

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

@char0n
Copy link
Member Author

char0n commented Dec 22, 2022

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
Copy link
Member Author

char0n commented Dec 22, 2022

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

char0n added a commit that referenced this issue Dec 22, 2022
Examples now don't contain any dev related fixtures.

Refs #3627
@char0n char0n closed this as completed Dec 22, 2022
swagger-bot pushed a commit that referenced this issue Dec 22, 2022
# [5.0.0-alpha.42](v5.0.0-alpha.41...v5.0.0-alpha.42) (2022-12-22)

### Features

* reorganize examples into File menu ([#3743](#3743)) ([7a9b13c](7a9b13c)), closes [#3627](#3627)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants