-
Notifications
You must be signed in to change notification settings - Fork 8.1k
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
[Security Solution] A proper location for OpenAPI specs #184859
Comments
Pinging @elastic/security-solution (Team: SecuritySolution) |
One of the ideas suggested by @banderror is to use Security Solution domain packages like
The only question is to decide where should resulting OAS bundles be placed
|
Zoomed with @marshallmain and @banderror regarding this topic. Discussed possible ways to solve bad DX related to relative schema imports like
|
Hi @marshallmain and @banderror, I've investigated usage of Base URI, OAS shared schemas re-exporting and using a package for schema primitives. TLDR: There is a no working solution out of the box. We need noticeable amount of effort to make it working. DetailsInvestigate usage of Base URII analyzed it from two different sides OAS and JSON schema specifications and tooling (
Analyzing JSON schema specification it becomes clear that references are considered as links. Links could be relative or absolute. Relative links resolved by using baseURI which is a URI the specification was retrieved from. Or baseURI can be explicitly specified via
Investigate OAS re-exportingI approached this part by creating a shared list schema in List plugin at openapi: 3.0.0
info:
title: Error Schema
version: 'not applicable'
paths: {}
components:
x-codegen-enabled: false
schemas:
List:
$ref: './values/model/list_common.schema.yaml#/components/schemas/List' then I referenced re-exported openapi: 3.0.0
info:
title: Test shared schemas re-export
version: 'not applicable'
paths: {}
components:
x-codegen-enabled: true
schemas:
TestSchema:
type: object
properties:
localId:
$ref: './primitives.schema.yaml#/components/schemas/NonEmptyString'
listData:
$ref: '../../../../lists/common/api/export.schema.yaml#/components/schemas/List' The problem with that approach is that Investigate placing OAS primitives like
|
@maximpn Thank you for doing this research and describing the results. My suggestion is:
|
Based on the research we decided to proceed with packages for OpenAPI specs as describe in the previous comment #184859 (comment). Actual code change will be addressed as a part of separate tickets |
Epic: https://github.com/elastic/security-team/issues/9401 (internal)
Summary
While working on adding missing OpenAPI spec (OAS) for Detections API it became prominent that the current OAS placement in
security_solution/common/api
brings the following challengesBad DX when using OAS references e.g.
../../../../../../../lists/common/api/exceptions/exception.schema.yaml
Some API endpoints (e.g.
POST /api/detection_engine/rules/{id}/exceptions
) have external dependencies. It requires referencing shared OAS schemas via$ref
from the other plugins (e.g.lists
). Having such long relative paths is brittle and inconvenient. Moving OAS files to another folder will be painful. There is no aliasing solution out of the box.A necessity to import generated Zod schemas and inferred types from the other plugins.
Currently we have
io-ts
schemas defined in plugins e.g.kbn-securitysolution-io-ts-list-types
.NonEmptyString
orUUID
) location. What's a proper location for them?There some shared OAS schemas considered like primitives like
NonEmptyString
andUUID
defined in Security Solution plugin. Obviously such primitives need to be reused in the other plugins.The text was updated successfully, but these errors were encountered: