Skip to content

Commit

Permalink
[Docs] Added callout to docs team to OAS tutorial (#187750)
Browse files Browse the repository at this point in the history
<img width="768" alt="Screenshot 2024-07-08 at 16 03 41"
src="https://github.com/elastic/kibana/assets/8155004/9e1c2cbc-f802-412e-a289-ff356efe978c">
  • Loading branch information
jloleysens authored Jul 8, 2024
1 parent bac808a commit 5c85569
Showing 1 changed file with 5 additions and 1 deletion.
6 changes: 5 additions & 1 deletion dev_docs/tutorials/generating_oas_for_http_apis.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,10 @@ Other useful query parameters for filtering are:
* `pluginId` - get the OAS for a specific plugin, for example: `@kbn/data-views-plugin`
* `access` - filter for specific access levels: `public` or `internal` are supported

<DocCallOut>
For assistance with the writing docs or any other questions about the docs impact, check out https://docs.elastic.dev/content-architecture/oas or chat with writers on **#docs** or **#next-api-reference**
</DocCallOut>

### Some good practices to consider

#### 1. Runtime schema definitions
Expand Down Expand Up @@ -172,7 +176,7 @@ OAS for public routes are written to the Kibana repo as a snapshot that will ult
#### What about runtime validation libary X?
Teams have adopted different runtime validation libraries for their HTTP APIs. Kibana core does not intend to support all runtime validation libraries.

Reach out to #kibana-core with questions, concerns or issues you may be facing with `@kbn/config-schema` and we will help you find a solution.
Reach out to **#kibana-core** with questions, concerns or issues you may be facing with `@kbn/config-schema` and we will help you find a solution.

#### What about internal HTTP APIs?
It's possible to generate OpenAPI specification for `access: 'internal'` routes but it is not required. The benefit will largely be for your team's internal reference and for other teams to discover your APIs. If you follow the practices outlined in this tutorial it should be simple to generate OAS for internal routes as well.

0 comments on commit 5c85569

Please sign in to comment.