Docs/targetsource userguide push

.gitignore

@@ -33,4 +33,6 @@ notes/
 docs/public
 docs/resources/_gen/
 docs/.hugo_build.lock
-test/integration/clab-*
+test/integration/clab-*
+docs/content/docs/advanced/rest-api-documentation/.openapi-generator
+docs/content/docs/advanced/rest-api-documentation/.openapi-generator-ignore

docs/content/docs/Apis/DefaultApi.md

@@ -0,0 +1,2 @@
+# DefaultApi
+

docs/content/docs/advanced/openapi-generator-config.yaml

@@ -0,0 +1,9 @@
+# docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate  -c /local/docs/content/docs/advanced/openapi-generator-config.yaml
+
+generatorName: markdown
+inputSpec: /local/internal/apiserver/openapi.yaml
+outputDir: /local/docs/content/docs/advanced/rest-api-documentation
+templateDir: /local/docs/content/docs/advanced/openapi-templates/markdown-documentation
+files:
+  README.mustache:
+    destinationFilename: _index.md

docs/content/docs/advanced/openapi-templates/markdown-documentation/README.mustache

@@ -0,0 +1,69 @@
+---
+title: "REST API interface"
+linkTitle: "REST API interface"
+weight: 3
+description: >
+  This document describes the REST API exposed by the gNMIc Operator, including the available endpoints, request formats, and usage examples.
+---
+
+{{#generateApiDocs}}
+<a name="documentation-for-api-endpoints"></a>
+## Documentation for API Endpoints
+
+All URIs are relative to *{{{basePath}}}:8082*
+
+| Class | Method | HTTP request | Description |
+|------------ | ------------- | ------------- | -------------|
+{{#apiInfo}}{{#apis}}{{#operations}}| {{#operation}}*{{#lambda.lowercase}}{{classname}}{{/lambda.lowercase}}* | [**{{operationId}}**](/docs/advanced/rest-api-documentation/apis/{{#lambda.lowercase}}{{classname}}{{/lambda.lowercase}}) | **{{httpMethod}}** {{path}} | {{{summary}}}{{^summary}}{{{notes}}}{{/summary}} |
+{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
+{{/generateApiDocs}}
+
+{{#generateModelDocs}}
+<a name="documentation-for-models"></a>
+## Documentation for Models
+
+{{#modelPackage}}
+{{#models}}{{#model}} - [{{#lambda.lowercase}}{{{classname}}}{{/lambda.lowercase}}](/docs/advanced/rest-api-documentation/models/{{#lambda.lowercase}}{{{classFilename}}}{{/lambda.lowercase}}/)
+{{/model}}{{/models}}
+{{/modelPackage}}
+{{^modelPackage}}
+No model defined in this package
+{{/modelPackage}}
+{{/generateModelDocs}}
+
+<a name="documentation-for-authorization"></a>{{! TODO: optional documentation for authorization? }}
+## Documentation for Authorization
+
+For a detailed explanation on how to configure the required secrets within the gNMIc Operator, refer to [TargetSource > Push mode](/docs/user-guide/targetsource/push/).
+
+{{^authMethods}}
+All endpoints do not require authorization.
+{{/authMethods}}
+{{#authMethods}}
+{{#last}}
+    Authentication schemes defined for the API:
+{{/last}}
+{{/authMethods}}
+{{#authMethods}}
+<a name="{{name}}"></a>
+### {{name}}
+
+{{#isApiKey}}- **Type**: API key
+- **API key parameter name**: {{keyParamName}}
+- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
+{{/isApiKey}}
+{{#isBasicBasic}}- **Type**: HTTP basic authentication
+{{/isBasicBasic}}
+{{#isBasicBearer}}- **Type**: HTTP Bearer Token authentication{{#bearerFormat}} ({{{.}}}){{/bearerFormat}}
+{{/isBasicBearer}}
+{{#isHttpSignature}}- **Type**: HTTP signature authentication
+{{/isHttpSignature}}
+{{#isOAuth}}- **Type**: OAuth
+- **Flow**: {{flow}}
+- **Authorization URL**: {{authorizationUrl}}
+- **Scopes**: {{^scopes}}N/A{{/scopes}}
+{{#scopes}}  - {{scope}}: {{description}}
+{{/scopes}}
+{{/isOAuth}}
+
+{{/authMethods}}

docs/content/docs/advanced/openapi-templates/markdown-documentation/api.mustache

@@ -0,0 +1,50 @@
+---
+title: "Routes"
+linkTitle: "Routes"
+weight: 4
+description: >
+  Available HTTP routes on the gNMIc Operator API interface.
+---
+
+# {{#lambda.lowercase}}{{classname}}{{/lambda.lowercase}}{{#description}}
+    {{.}}{{/description}}
+
+All URIs are relative to *{{basePath}}:8082*
+
+| Method | HTTP request | Description |
+|------------- | ------------- | -------------|
+{{#operations}}{{#operation}}| **{{operationId}}** | **{{httpMethod}}** {{path}} | {{summary}} |
+{{/operation}}{{/operations}}
+
+{{#operations}}
+{{#operation}}
+<a name="{{operationId}}"></a>
+# **{{operationId}}**
+> {{#returnType}}{{.}} {{/returnType}}{{operationId}}({{#allParams}}{{{paramName}}}{{^-last}}, {{/-last}}{{/allParams}})
+
+{{summary}}{{#notes}}
+
+    {{.}}{{/notes}}
+
+### Parameters
+{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|{{/-last}}{{/allParams}}
+{{#allParams}}| **{{paramName}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{#isFile}}**{{dataType}}**{{/isFile}}{{^isFile}}{{#generateModelDocs}}[**{{dataType}}**](/docs/advanced/rest-api-documentation/models/{{#lambda.lowercase}}{{baseType}}{{/lambda.lowercase}}/){{/generateModelDocs}}{{^generateModelDocs}}**{{dataType}}**{{/generateModelDocs}}{{/isFile}}{{/isPrimitiveType}}| {{description}} |{{^required}} [optional]{{/required}}{{#defaultValue}} [default to {{.}}]{{/defaultValue}}{{#allowableValues}} [enum: {{#values}}{{{.}}}{{^-last}}, {{/-last}}{{/values}}]{{/allowableValues}} |
+{{/allParams}}
+
+### Return type
+
+{{#returnType}}{{#returnTypeIsPrimitive}}**{{returnType}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}{{#generateModelDocs}}[**{{returnType}}**](/docs/advanced/rest-api-documentation/models/{{#lambda.lowercase}}{{returnBaseType}}{{/lambda.lowercase}}/){{/generateModelDocs}}{{^generateModelDocs}}**{{returnType}}**{{/generateModelDocs}}{{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}null (empty response body){{/returnType}}
+
+### Authorization
+
+{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{name}}](/docs/advanced/rest-api-documentation/#{{name}}){{^-last}}, {{/-last}}{{/authMethods}}
+
+### HTTP request headers
+
+- **Content-Type**: {{#consumes}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
+- **Accept**: {{#produces}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/produces}}{{^produces}}Not defined{{/produces}}
+
+{{/operation}}
+{{/operations}}

docs/content/docs/advanced/openapi-templates/markdown-documentation/model.mustache

@@ -0,0 +1,29 @@
+---
+title: "Model"
+linkTitle: "Model"
+weight: 4
+description: >
+  Documentation for OpenAPI models and their schema-defined properties.
+---
+
+{{#models}}
+{{#model}}
+# {{#lambda}}{{{classname}}}{{/lambda}}
+{{#description}}
+{{{description}}}
+{{/description}}
+
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+{{#parent}}
+{{#parentVars}}
+| **{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{#lambda.lowercase}}{{complexType}}{{/lambda.lowercase}}.md){{/isPrimitiveType}} | {{{description}}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} |
+{{/parentVars}}
+{{/parent}}
+{{#vars}}| **{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{#lambda.lowercase}}{{complexType}}{{/lambda.lowercase}}.md){{/isPrimitiveType}} | {{{description}}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} |
+{{/vars}}
+
+    {{/model}}
+{{/models}}

docs/content/docs/advanced/rest-api-documentation.md

@@ -0,0 +1,33 @@
+---
+title: "Documentation for gNMIc Operator REST API"
+linkTitle: "REST API interface"
+weight: 3
+description: >
+  Documentation of REST API interface according to openAPI standard.
+---
+
+<a name="documentation-for-api-endpoints"></a>
+## Documentation for API Endpoints
+
+All URIs are relative to *http://localhost*
+
+| Class | Method | HTTP request | Description |
+|------------ | ------------- | ------------- | -------------|
+| *DefaultApi* | [**applyTargets**](../Apis/DefaultApi.md#applyTargets) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. |
+*DefaultApi* | [**getClusterPlan**](../Apis/DefaultApi.md#getClusterPlan) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. |
+
+
+<a name="documentation-for-models"></a>
+## Documentation for Models
+
+ - [Target](../Models/Target.md)
+
+
+<a name="documentation-for-authorization"></a>
+## Documentation for Authorization
+
+<a name="bearerAuth"></a>
+### bearerAuth
+
+- **Type**: HTTP Bearer Token authentication
+

docs/content/docs/advanced/rest-api-documentation/Apis/DefaultApi.md

@@ -0,0 +1,65 @@
+---
+title: "Routes"
+linkTitle: "Routes"
+weight: 4
+description: >
+  Available HTTP routes on the gNMIc Operator API interface.
+---
+
+# defaultapi
+
+All URIs are relative to *http://localhost:8082*
+
+| Method | HTTP request | Description |
+|------------- | ------------- | -------------|
+| **applyTargets** | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. |
+| **getClusterPlan** | **GET** /clusters/:namespace/:name/plan | Get cluster plan. |
+
+
+<a name="applyTargets"></a>
+# **applyTargets**
+> List applyTargets(Target)
+
+Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator.
+
+### Parameters
+
+|Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **Target** | [**List**](/docs/advanced/rest-api-documentation/models/target/)| Target must be passed as a list, multiple targets possible. | |
+
+### Return type
+
+[**List**](/docs/advanced/rest-api-documentation/models/target/)
+
+### Authorization
+
+[signature](/docs/advanced/rest-api-documentation/#signature), [bearerAuth](/docs/advanced/rest-api-documentation/#bearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: application/json
+- **Accept**: application/json
+
+<a name="getClusterPlan"></a>
+# **getClusterPlan**
+> getClusterPlan()
+
+Get cluster plan.
+
+### Parameters
+This endpoint does not need any parameter.
+
+### Return type
+
+null (empty response body)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: Not defined
+

docs/content/docs/advanced/rest-api-documentation/Models/Target.md

@@ -0,0 +1,22 @@
+---
+title: "Model"
+linkTitle: "Model"
+weight: 4
+description: >
+  Documentation for OpenAPI models and their schema-defined properties.
+---
+
+# Target
+Network device to be monitored. Properties not marked as optional must be in JSON body.
+
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **name** | **String** | Name of device to be monitored. | [default to null] |
+| **address** | **String** | IPv4/IPv6 address or hostname. | [default to null] |
+| **port** | **Integer** | gNMIc port. | [optional] [default to null] |
+| **targetProfile** | **String** | TargetProfile applied to apply to this router. | [optional] [default to null] |
+| **labels** | [**List**](map.md) | Input of labels as key:value pair. | [optional] [default to null] |
+| **operation** | **String** | Either `created`, `updated` or `deleted`. `created` and `updated` are identical and both apply the target. | [default to null] |
+

docs/content/docs/advanced/rest-api-documentation/_index.md

@@ -0,0 +1,42 @@
+---
+title: "REST API interface"
+linkTitle: "REST API interface"
+weight: 3
+description: >
+  This document describes the REST API exposed by the gNMIc Operator, including the available endpoints, request formats, and usage examples.
+---
+
+<a name="documentation-for-api-endpoints"></a>
+## Documentation for API Endpoints
+
+All URIs are relative to *http://localhost:8082*
+
+| Class | Method | HTTP request | Description |
+|------------ | ------------- | ------------- | -------------|
+| *defaultapi* | [**applyTargets**](/docs/advanced/rest-api-documentation/apis/defaultapi) | **POST** /api/v1/:namespace/target-source/:name/applyTargets | Interface for real-time target updates, usually using a webhook. Targets are applied in the gNMIc Operator. |
+*defaultapi* | [**getClusterPlan**](/docs/advanced/rest-api-documentation/apis/defaultapi) | **GET** /clusters/:namespace/:name/plan | Get cluster plan. |
+
+
+<a name="documentation-for-models"></a>
+## Documentation for Models
+
+ - [target](/docs/advanced/rest-api-documentation/models/target/)
+
+
+<a name="documentation-for-authorization"></a>
+## Documentation for Authorization
+
+For a detailed explanation on how to configure the required secrets within the gNMIc Operator, refer to [TargetSource > Push mode](/docs/user-guide/targetsource/push/).
+
+<a name="bearerAuth"></a>
+### bearerAuth
+
+- **Type**: HTTP Bearer Token authentication
+
+<a name="signature"></a>
+### signature
+
+- **Type**: API key
+- **API key parameter name**: X-Hook-Signature
+- **Location**: HTTP header
+

docs/content/docs/examples/NetBox/Export Template/_index.md

@@ -1,6 +1,6 @@
 ---
-title: "NetBox (Export Template)"
-linkTitle: "NetBox Export Template"
+title: "Pull with Export Template"
+linkTitle: "Pull with Export Template"
 weight: 1
 description: >
   Discover targets from NetBox using HTTP provider with NetBox Export Template
@@ -12,14 +12,14 @@ Export Templates offer powerful filtering, transformation, and formatting direct
 
 ## Overview
 
-An **Export Template** is a Jinja2 template defined in NetBox that:
+An **Export Template** is a Jinja2 template that:
 
 1. **Queries** NetBox's internal database (devices, interfaces, etc.)
 2. **Filters** results based on custom criteria
-3. **Transforms** data into your desired output format (JSON, YAML, CSV, etc.)
-4. **Returns** the formatted output via a custom REST API endpoint
+3. **Transforms** data into your desired output format
+4. **Returns** the formatted output via REST API endpoint
 
-When used with gNMIc's HTTP provider, the operator simply fetches the rendered JSON template and parses the result — no additional gNMIc Operator transformation needed if done correctly.
+When used with gNMIc's HTTP provider, the operator fetches the rendered JSON template and parses the result with no further transformation needed by the gNMIc Operator.
 
 ---
 

docs/content/docs/examples/NetBox/REST API/_index.md

@@ -1,6 +1,6 @@
 ---
-title: "NetBox (REST API)"
-linkTitle: "NetBox REST"
+title: "Pull with REST API"
+linkTitle: "Pull with REST API"
 weight: 2
 description: >
   Discover targets from NetBox using the HTTP provider and NetBox REST API