elastic · kilfoyle · Mar 2, 2023 · Feb 25, 2023 · Feb 25, 2023 · Feb 25, 2023
@@ -0,0 +1,34 @@
+ OpenAPI (Experimental)
+
+The process described here is a Fleet-specific instance of the process described for generating Kibana OpenAPI documentation in general. Refer to the Kibana OpenAPI [readme file](https://github.com/elastic/kibana/tree/main/docs/api-generated) for details.
+
+Open API specifications (OAS) exist in JSON for Fleet, though they are experimental and may be incomplete or change later.
+
+A preview of the API specifications can be added to the Fleet and Elastic Agent Guide by using the following process:
+
+. Create a local clone of the [elastic/kibana](https://github.com/elastic/kibana) and [elastic/observability-docs](https://github.com/elastic/observability-docs) repositories in your `$GIT_PATH` directory.
+
+. Install [OpenAPI Generator](https://openapi-generator.tech/docs/installation),
+or a similar tool that can generate HTML output from OAS.
+
+. Optionally validate the specifications by using the commands listed in the appropriate readmes.
+
+. Generate HTML output. For example:
+
+  ```
+  openapi-generator generate -g html -i $GIT_HOME/kibana/x-pack/plugins/fleet/common/openapi/bundled.json -o $GIT_HOME/observability-docs/docs/en/ingest-management/fleet/api-generated/rules -t $GIT_HOME/observability-docs/docs/en/ingest-management/fleet/api-generated/template
+  ```
+
+. Rename the output files. For example:
+  ```
+  mv $GIT_HOME/observability-docs/docs/en/ingest-management/fleet/api-generated/rules/index.html $GIT_HOME/observability-docs/docs/en/ingest-management/fleet/api-generated/rules/fleet-apis-passthru.asciidoc
+  ```
+
+. If you're creating a new set of API output, you will need to have a page that incorporates the output by using passthrough blocks. For more information, refer to [Asciidoctor docs](https://docs.asciidoctor.org/asciidoc/latest/pass/pass-block/)
+
+. Verify the output by building the Kibana documentation. At this time, the output is added as a technical preview in the appendix.
+
+## Known issues
+
+- Some OAS 3.0 features such as `anyOf`, `oneOf`, and `allOf` might not display properly in the preview. These are on the [Short-term roadmap](https://openapi-generator.tech/docs/roadmap/) at this time.
+
@@ -0,0 +1,23 @@
+# OpenAPI Generator Ignore
+# Generated by openapi-generator https://github.com/openapitools/openapi-generator
+
+# Use this file to prevent files from being overwritten by the generator.
+# The patterns follow closely to .gitignore or .dockerignore.
+
+# As an example, the C# client generator defines ApiClient.cs.
+# You can make changes and tell OpenAPI Generator to ignore just this file by uncommenting the following line:
+#ApiClient.cs
+
+# You can match any string of characters against a directory, file or extension with a single asterisk (*):
+#foo/*/qux
+# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux
+
+# You can recursively match patterns against a directory, file or extension with a double asterisk (**):
+#foo/**/qux
+# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux
+
+# You can also negate patterns with an exclamation (!).
+# For example, you can ignore all files in a docs folder with the file extension .md:
+#docs/*.md
+# Then explicitly reverse the ignore rule for a single file:
+#!docs/README.md
@@ -0,0 +1 @@
+index.html
@@ -0,0 +1 @@
+6.4.0
@@ -0,0 +1,10 @@
+[[fleet-apis]]
+== Fleet APIs
+
+preview::[]
+
+////
+This file includes content that has been generated from https://github.com/elastic/kibana/tree/main/x-pack/plugins/fleet/common/openapi. Any modifications required must be done in that open API specification.
+////
+
+include::fleet-apis-passthru.asciidoc[]
@@ -0,0 +1,173 @@
+////
+This content is generated from the open API specification.
+Any modifications made to this file will be overwritten.
+////
+
+++++
+<div class="openapi">
+
+<!--
+  <h2>Access</h2>
+  {{#hasAuthMethods}}
+    <ol>
+    {{#authMethods}}
+      <li>{{#isBasic}}HTTP Basic Authentication{{/isBasic}}{{#isOAuth}}OAuth AuthorizationUrl:{{authorizationUrl}}TokenUrl:{{tokenUrl}}{{/isOAuth}}{{#isApiKey}}APIKey KeyParamName:{{keyParamName}} KeyInQuery:{{isKeyInQuery}} KeyInHeader:{{isKeyInHeader}}{{/isApiKey}}</li>
+    {{/authMethods}}
+    </ol>
+  {{/hasAuthMethods}}
+-->
+
+  <h2><a name="__Methods">Methods</a></h2>
+  [ Jump to <a href="#__Models">Models</a> ]
+
+  {{! for the tables of content, I cheat and don't use CSS styles.... }}
+  <h3>Table of Contents </h3>
+  <div class="method-summary">{{access}}</div>
+  {{#apiInfo}}
+  {{#apis}}
+  {{#operations}}
+  <h4><a href="#{{baseName}}">{{baseName}}</a></h4>
+  <ul>
+  {{#operation}}
+  <li><a href="#{{nickname}}"><code><span class="http-method">{{httpMethod}}</span> {{path}}</code></a></li>
+  {{/operation}}
+  </ul>
+  {{/operations}}
+  {{/apis}}
+  {{/apiInfo}}
+
+  {{#apiInfo}}
+  {{#apis}}
+  {{#operations}}
+  <h1><a name="{{baseName}}">{{baseName}}</a></h1>
+  {{#operation}}
+  <div class="method"><a name="{{nickname}}"/>
+    <div class="method-path">
+    <a class="up" href="#__Methods">Up</a>
+    <pre class="{{httpMethod}}"><code class="huge"><span class="http-method">{{httpMethod}}</span> {{path}}</code></pre></div>
+    <div class="method-summary">{{summary}} (<span class="nickname">{{nickname}}</span>)</div>
+    {{! notes is operation.description. So why rename it and make it super confusing???? }}
+    <div class="method-notes">{{notes}}</div>
+
+    {{#hasPathParams}}
+    <h3 class="field-label">Path parameters</h3>
+    <div class="field-items">
+      {{#pathParams}}{{>pathParam}}{{/pathParams}}
+    </div>  <!-- field-items -->
+    {{/hasPathParams}}
+
+    {{#hasConsumes}}
+    <h3 class="field-label">Consumes</h3>
+    This API call consumes the following media types via the <span class="header">Content-Type</span> request header:
+    <ul>
+    {{#consumes}}
+      <li><code>{{{mediaType}}}</code></li>
+    {{/consumes}}
+    </ul>
+    {{/hasConsumes}}
+
+    {{#hasBodyParam}}
+    <h3 class="field-label">Request body</h3>
+    <div class="field-items">
+      {{#bodyParams}}{{>bodyParam}}{{/bodyParams}}
+    </div>  <!-- field-items -->
+    {{/hasBodyParam}}
+
+    {{#hasHeaderParams}}
+    <h3 class="field-label">Request headers</h3>
+    <div class="field-items">
+      {{#headerParams}}{{>headerParam}}{{/headerParams}}
+    </div>  <!-- field-items -->
+    {{/hasHeaderParams}}
+
+    {{#hasQueryParams}}
+    <h3 class="field-label">Query parameters</h3>
+    <div class="field-items">
+      {{#queryParams}}{{>queryParam}}{{/queryParams}}
+    </div>  <!-- field-items -->
+    {{/hasQueryParams}}
+
+    {{#hasFormParams}}
+    <h3 class="field-label">Form parameters</h3>
+    <div class="field-items">
+      {{#formParams}}{{>formParam}}{{/formParams}}
+    </div>  <!-- field-items -->
+    {{/hasFormParams}}
+
+    {{#returnType}}
+    <h3 class="field-label">Return type</h3>
+    <div class="return-type">
+      {{#hasReference}}{{^returnSimpleType}}{{returnContainer}}[{{/returnSimpleType}}<a href="#{{returnBaseType}}">{{returnBaseType}}</a>{{^returnSimpleType}}]{{/returnSimpleType}}{{/hasReference}}
+      {{^hasReference}}{{returnType}}{{/hasReference}}
+    </div>
+    {{/returnType}}
+
+    <!--Todo: process Response Object and its headers, schema, examples -->
+
+    {{#hasExamples}}
+    {{#examples}}
+    <h3 class="field-label">Example data</h3>
+    <div class="example-data-content-type">Content-Type: {{{contentType}}}</div>
+    <pre class="example"><code>{{{example}}}</code></pre>
+    {{/examples}}
+    {{/hasExamples}}
+
+    {{#hasProduces}}
+    <h3 class="field-label">Produces</h3>
+    This API call produces the following media types according to the <span class="header">Accept</span> request header;
+    the media type will be conveyed by the <span class="header">Content-Type</span> response header.
+    <ul>
+    {{#produces}}
+      <li><code>{{{mediaType}}}</code></li>
+    {{/produces}}
+    </ul>
+    {{/hasProduces}}
+
+    <h3 class="field-label">Responses</h3>
+    {{#responses}}
+    <h4 class="field-label">{{code}}</h4>
+    {{message}}
+        {{^containerType}}<a href="#{{dataType}}">{{dataType}}</a>{{/containerType}}
+    {{#examples}}
+    <h3 class="field-label">Example data</h3>
+    <div class="example-data-content-type">Content-Type: {{{contentType}}}</div>
+    <pre class="example"><code>{{example}}</code></pre>
+    {{/examples}}
+    {{/responses}}
+  </div> <!-- method -->
+  <hr/>
+  {{/operation}}
+  {{/operations}}
+  {{/apis}}
+  {{/apiInfo}}
+
+  <h2><a name="__Models">Models</a></h2>
+  [ Jump to <a href="#__Methods">Methods</a> ]
+
+  <h3>Table of Contents</h3>
+  <ol>
+  {{#models}}
+  {{#model}}
+    <li><a href="#{{name}}"><code>{{name}}</code>{{#title}} - {{.}}{{/title}}</a></li>
+  {{/model}}
+  {{/models}}
+  </ol>
+
+  {{#models}}
+  {{#model}}
+  <div class="model">
+    <h3><a name="{{name}}"><code>{{name}}</code>{{#title}} - {{.}}{{/title}}</a> <a class="up" href="#__Models">Up</a></h3>
+    {{#unescapedDescription}}<div class='model-description'>{{.}}</div>{{/unescapedDescription}}
+    <div class="field-items">
+      {{#vars}}<div class="param">{{name}} {{^required}}(optional){{/required}}</div><div class="param-desc"><span class="param-type">{{^isPrimitiveType}}<a href="#{{complexType}}">{{dataType}}</a>{{/isPrimitiveType}}</span> {{unescapedDescription}} {{#dataFormat}}format: {{{.}}}{{/dataFormat}}</div>
+      {{#isEnum}}
+        <div class="param-enum-header">Enum:</div>
+        {{#_enum}}<div class="param-enum">{{this}}</div>{{/_enum}}
+      {{/isEnum}}
+      {{/vars}}
+    </div>  <!-- field-items -->
+  </div>
+  {{/model}}
+  {{/models}}
+</div>
+++++
@@ -0,0 +1,14 @@
+[role="exclude",id="apis"]
+= API
+
+[partintro]
+--
+
+preview::[]
+
+The {fleet} API is documented using the OpenAPI specification. The current supported
+version of the specification is 3.0. For more information, go to https://openapi-generator.tech/[OpenAPI Generator]
+
+--
+
+include::api-generated/rules/fleet-apis.asciidoc[]
@@ -3,14 +3,23 @@
 
 experimental[]
 
-The official {fleet} API documentation is not yet available in the Elastic docs.
-However we do provide a self-contained spec file that you can
-https://petstore.swagger.io/?url=https://raw.githubusercontent.com/elastic/kibana/{branch}/x-pack/plugins/fleet/common/openapi/bundled.json[view in Swagger]
-(or a similar tool) to explore our Fleet APIs.
+You can find details for all available {fleet} API endpoints in our generated
+<<fleet-apis,{fleet} API docs>>. This documentation is experimental and may be
+incomplete or change later.
 
+The main source of truth for the {fleet} API can be found in the
+https://github.com/elastic/kibana/blob/main/x-pack/plugins/fleet/common/openapi/bundled.json[self-contained spec file]
+that you can use to generate docs using Swagger or a similar tool.
 For more information, refer to the
-https://github.com/elastic/kibana/blob/{branch}/x-pack/plugins/fleet/common/openapi/README.md[{fleet} OpenAPI file]
-in the {kib} repository.
+https://github.com/elastic/kibana/tree/main/x-pack/plugins/fleet/common/openapi/README.md[{fleet} OpenAPI readme].
+
+//However we do provide a self-contained spec file that you can
+//https://petstore.swagger.io/?url=https://raw.githubusercontent.com/elastic/kibana/{branch}/x-pack/plugins/fleet/common/openapi/bundled.json[view in Swagger]
+//(or a similar tool) to explore our Fleet APIs.
+
+//For more information, refer to the
+//https://github.com/elastic/kibana/blob/{branch}/x-pack/plugins/fleet/common/openapi/README.md[{fleet} OpenAPI file]
+//in the {kib} repository.
 
 In this section, we provide examples of some commonly used {fleet} APIs.
 

@@ -179,4 +179,6 @@ include::release-notes/release-notes-8.6.asciidoc[leveloffset=+1]
 
 include::elastic-agent/install-fleet-managed-agent.asciidoc[leveloffset=+2]
 
+include::fleet/apis.asciidoc[]
+
 include::redirects.asciidoc[]
Original file line number	Diff line number	Diff line change
Expand Up		@@ -179,4 +179,6 @@ include::release-notes/release-notes-8.6.asciidoc[leveloffset=+1]

		include::elastic-agent/install-fleet-managed-agent.asciidoc[leveloffset=+2]

		include::fleet/apis.asciidoc[]

		include::redirects.asciidoc[]