Create OpenAPI 3.x persistence layer and UI to support API Specification Management

[dubnemo]

Leverage the attached DDL to create tables that provide OpenAPI 3.x persistence layer to support API Specification Management. This may need to be adjusted as it was generated using http://www.sqlines.com/online.

Here is the detail of the ERD: https://oagiscore.atlassian.net/wiki/spaces/AD/pages/229998611/Entity+Relationship+Model+for+OpenAPI+Specification

Wireframes are here. Top Level: https://oagiscore.atlassian.net/wiki/spaces/AD/pages/229933066/OAS+API+Definition+-+Doc+and+Info+Wireframe Resource Level: https://oagiscore.atlassian.net/wiki/spaces/AD/pages/250675213/OAS+Resource+Definition+Wireframe

This would could be released in a 2.5 milestone. This does not introduce breaking changes.

[dubnemo]

MySQL DDL oas_mysql.zip

[hakjuoh]

@dubnemo @kbserm This file contains the data model of MySQLWorkbench and MySQL DDL manually ported from Oracle DDL oas_mysql.zip

I made some changes for the naming convention using "snake_case". Here's differences:

• Tables

oas_externalDoc -> oas_external_doc oas_externalDoc_doc -> oas_external_doc_doc oas_mediatype -> oas_media_type response_headers -> oas_response_headers // Put oas_ prefix to find oas-related tables easier

• Columns

oas_externalDoc.oas_externalDoc_id -> oas_external_doc.oas_external_doc_id oas_externalDoc_doc.oas_externalDoc_id -> oas_external_doc_doc.oas_external_doc_id oas_doc.termsOfService -> oas_doc.terms_of_service oas_operation.operationId -> oas_operation.operation_id oas_mediatype.oas_mediaType_id -> oas_media_type.oas_media_type_id oas_request.content_mediaType_id -> oas_request.content_media_type_id oas_request.include_metaHeader_indicator -> oas_request.include_meta_header_indicator oas_response.content_mediaType_id -> oas_response.content_media_type_id oas_response.include_metaHeader_indicator -> oas_response.include_meta_header_indicator oas_parameter.allowReserved -> oas_parameter.allow_reserved

@dubnemo Can I change the table name oas_resource_tag to oas_operation_tag? Because the primary key of the oas_resource_tag table is a combination of (oas_operation_id and oas_tag_id).

[dubnemo]

@hakjuoh Yes, the table name change makes sense. I will find time to update my ERD for the sake of Confluence sync. @kbserm

[hakjuoh]

@dubnemo @kbserm Applied changes for oas_doc_server table on MySQL DDL and Data Model. It uploaded on Confluence either.

[dubnemo]

@hakjuoh @kbserm @sfohn @jim-wilson-kt @michaelfigura There may be value to look at Stoplight's tool from a UI layout.
https://stoplight.io/studio

I know we went to great lengths to create wireframes, but they have a number of good layouts.

There are open source tools provided as well for mock server, linting and markdown generation: https://stoplight.io/open-source

[dubnemo]

1492 brings us very close to completing the OpenAPI Management issue here. @hakjuoh @kbserm

From Slack chat with @bingqi2045 ScottNieman 2:36 PM

Do you know that the ONLY remaining change we would need to be 100% complete with the original Issue 862 is the edit of an Endpoint Detail UI ? That would allow the specification detail of parameters (query, path, http headers). If a POST or PATCH is specified, both BIE references would be displayed, matching on the DEN, verb, and resource path, as the request and response are paired together. Picture double clicking on the BIE DEN and opening this detail, and allowing this edit. Currently you navigate to the BIE directly - that type of navigation would be via checkbox -> Edit BIE button, not double click. That is NOT for v3.2, but another day. (edited)

Bingqi Cheng 2:39 PM I see 2:39 we move it to next version

============= and we can discuss for 3.3.

[dubnemo]

This is the OpenAPI reference for Describing Parameters: https://swagger.io/docs/specification/describing-parameters/

- in: query
          name: format
          required: true
          schema:
            type: string
            enum: [json, xml, yaml]
          deprecated: true
          description: Deprecated, use the appropriate `Accept` header instead.

[dubnemo]

@hakjuoh @elena-jelisic @kbserm @sfohn

The example table may be 'over-engineered'.

I think a simpler approach would be to have an example column on each table which currently foreign keys to the example table.
I do NOT see a need to reuse example payloads. Plus request parameters can have examples too

missing oas_request_headers table.

I think we over loaded the parameters table in the WG effort. It needs to be cloned from oas_response_headers table.

[hakjuoh]

[dubnemo]

@hakjuoh @kbserm @jim-wilson-kt @sfohn On behalf of AgGateway needs, this Moqup should be consider for a new release. We are having challenges managing query/ path and header parameters, and the example data feature could reduce the number BIEs created for an API.

This is a single 'resource endpoint' page that could work for any verb combination. Clearly, GET request would not have a visible example text box, etc.