Skip to content

Commit 91ee7ee

Browse files
MpdreamzMpdreamz
authored
Fix/doc gen 5.3 (#2679)
* Update CodeGeneration to 5.3 The rest spec contains some breaking changes so added support of adding *.obsolete.json spec files to patch them without manually rewriting the spec files themselves. - query parameters for various endpoints have removed most notably delete/update_by_query and search related endpoints - Suggest GET was removed from the spec in 5.2 - CatThreadPools was badly documented (missing url part). * remove exist_source (new API in master not 5.3), include _common.json in project
1 parent d3ea346 commit 91ee7ee

File tree

157 files changed

+9852
-6108
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

157 files changed

+9852
-6108
lines changed

‎docs/aggregations/bucket/adjacency-matrix/adjacency-matrix-usage.asciidoc‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/5.0
2+
3+
:github: https://github.com/elastic/elasticsearch-net
4+
5+
:nuget: https://www.nuget.org/packages
6+
7+
////
8+
IMPORTANT NOTE
9+
==============
10+
This file has been generated from https://github.com/elastic/elasticsearch-net/tree/5.x/src/Tests/Aggregations/Bucket/AdjacencyMatrix/AdjacencyMatrixUsageTests.cs.
11+
If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file,
12+
please modify the original csharp file found at the link and submit the PR with that change. Thanks!
13+
////
14+
15+
[[adjacency-matrix-usage]]
16+
== Adjacency Matrix Usage
17+
18+
=== Object Initializer Syntax Example
19+
20+
[source,csharp]
21+
----
22+
new SearchRequest<Project>
23+
{
24+
Size = 0,
25+
Aggregations = new AdjacencyMatrixAggregation("interactions")
26+
{
27+
Filters = new NamedFiltersContainer
28+
{
29+
{ "grpA", new TermQuery { Field = "state", Value = StateOfBeing.BellyUp } },
30+
{ "grpB", new TermQuery { Field = "state", Value = StateOfBeing.Stable } },
31+
{ "grpC", new TermQuery { Field = "state", Value = StateOfBeing.VeryActive } },
32+
}
33+
}
34+
}
35+
----
36+
37+
[source,javascript]
38+
.Example json output
39+
----
40+
{
41+
"size": 0,
42+
"aggs": {
43+
"interactions": {
44+
"adjacency_matrix": {
45+
"filters": {
46+
"grpA": {
47+
"term": {
48+
"state": {
49+
"value": "BellyUp"
50+
}
51+
}
52+
},
53+
"grpB": {
54+
"term": {
55+
"state": {
56+
"value": "Stable"
57+
}
58+
}
59+
},
60+
"grpC": {
61+
"term": {
62+
"state": {
63+
"value": "VeryActive"
64+
}
65+
}
66+
}
67+
}
68+
}
69+
}
70+
}
71+
}
72+
----
73+
74+
=== Fluent DSL Example
75+
76+
[source,csharp]
77+
----
78+
s => s
79+
.Size(0)
80+
.Aggregations(aggs => aggs
81+
.AdjacencyMatrix("interactions", am => am
82+
.Filters(fs => fs
83+
.Filter("grpA", f => f.Term(p => p.State, StateOfBeing.BellyUp))
84+
.Filter("grpB", f => f.Term(p => p.State, StateOfBeing.Stable))
85+
.Filter("grpC", f => f.Term(p => p.State, StateOfBeing.VeryActive))
86+
)
87+
)
88+
)
89+
----
90+
91+
=== Handling Responses
92+
93+
[source,csharp]
94+
----
95+
response.ShouldBeValid();
96+
var interactions = response.Aggs.AdjacencyMatrix("interactions");
97+
interactions.Should().NotBeNull();
98+
var buckets = interactions.Buckets;
99+
buckets.Should().NotBeNullOrEmpty();
100+
101+
foreach (var bucket in buckets)
102+
{
103+
bucket.Key.Should().NotBeNullOrEmpty();
104+
bucket.DocCount.Should().BeGreaterThan(0);
105+
}
106+
----
107+

‎docs/client-concepts/certificates/working-with-certificates.asciidoc‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/5.0
2+
3+
:github: https://github.com/elastic/elasticsearch-net
4+
5+
:nuget: https://www.nuget.org/packages
6+
7+
////
8+
IMPORTANT NOTE
9+
==============
10+
This file has been generated from https://github.com/elastic/elasticsearch-net/tree/5.x/src/Tests/ClientConcepts/Certificates/WorkingWithCertificates.doc.cs.
11+
If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file,
12+
please modify the original csharp file found at the link and submit the PR with that change. Thanks!
13+
////
14+
15+
[[working-with-certificates]]
16+
== Working with certificates
17+
18+
=== Server Certificates
19+
20+
If you've enabled SSL on elasticsearch with x-pack or through a proxy in front of elasticsearch and the Certificate Authority (CA)
21+
That generated the certificate is trusted by the machine running the client code there should be nothing you'll have to do to to talk
22+
to over https with the client. If you are using your own CA which is not trusted .NET won't allow you to make https calls to that endpoint.
23+
24+
.NET allows you to preempt this though through a custom validation through the the global static `ServicePointManager.ServerCertificateValidationCallback`.
25+
Most examples you will find on the .NET will simply return `true` from this delegate and call it quits. This is not advisable as this will allow any HTTPS
26+
traffic in the current AppDomain and not run any validations. Imagine you deploy a web app that talks to Elasticsearch over HTTPS but also some third party
27+
SOAP/WSDL endpoint setting `ServicePointManager.ServerCertificateValidationCallback += (sender, cert, chain, errors) => true;` will skip validation of BOTH
28+
Elasticsearch and that external web service.
29+
30+
.NET also allows you to set that callback per service endpoint and Elasticsearch.NET/NEST exposes this through connection settings.
31+
You can do your own validation in that handler or simply assign baked in handler that we ship with out of the box on the static
32+
class `CertificateValidations`.
33+
34+
The two most basic ones are `AllowAll` and `DenyAll` which does accept or deny any ssl trafic to our nodes`:
35+
36+
If your client application however has access to the public CA certificate locally Elasticsearch.NET/NEST ships with handy helpers that assert
37+
that the certificate that the server presented was one that came from our local CA certificate. If you use x-pack's `certgen` tool to
38+
[generate SSL certificates] https://www.elastic.co/guide/en/x-pack/current/ssl-tls.html)[] the generated node certificate does not include the CA in the
39+
certificate chain. This to cut back on SSL handshake size. In those case you can use `CertificateValidations.AuthorityIsRoot` and pass it your local copy
40+
of the CA public key to assert that the certificate the server presented was generated off that.
41+
42+
If your local copy does not match the servers CA Elasticsearch.NET/NEST will fail to connect
43+
44+
If you go for a vendor generated SSL certificate its common practice for them to include the CA and any intermediary CA's in the certificate chain
45+
in those case use `CertificateValidations.AuthorityPartOfChain` which validates that the local CA certificate is part of that chain and was used to
46+
generate the servers key.
47+
48+
=== Client Certificates
49+
50+
X-Pack also allows you to configure a [PKI realm] https://www.elastic.co/guide/en/x-pack/current/pki-realm.html)[] to enable user authentication
51+
through client certificates. The `certgen` tool included with X-Pack allows you to
52+
[generate client certificates as well] https://www.elastic.co/guide/en/x-pack/current/ssl-tls.html#CO13-4)[] and assign the distinguished name (DN) of the
53+
certificate as a user with a certain role.
54+
55+
certgen by default only generates a public certificate `.cer`) and a private key `.key`. To authenticate with client certificates you need to present both
56+
as one certificate. The easiest way to do this is to generate a `pfx` or `p12` file from the two and present that to `new X509Certificate(pathToPfx)`.
57+
58+
If you do not have a way to run `openssl` or `Pvk2Pfx` to do so as part of your deployments the clients ships with a handy helper to generate one
59+
on the fly in code based of `.cer` and `.key` files that `certgen` outputs. Sadly this is not available on .NET core because we can no longer set `PublicKey`
60+
crypto service provider.
61+
62+
You can set Client Certificates to use on all connections on `ConnectionSettings`
63+
64+
Or per request on `RequestConfiguration` which will take precedence over the ones defined on `ConnectionConfiguration`
65+
66+
=== Object Initializer Syntax Example
67+
68+
[source,csharp]
69+
----
70+
new RootNodeInfoRequest
71+
{
72+
RequestConfiguration = new RequestConfiguration
73+
{
74+
ClientCertificates = new X509Certificate2Collection { new X509Certificate2(this.BadCertificate) }
75+
}
76+
}
77+
----
78+
79+
=== Fluent DSL Example
80+
81+
[source,csharp]
82+
----
83+
s => s
84+
.RequestConfiguration(r => r
85+
.ClientCertificate(this.BadCertificate)
86+
87+
)
88+
----
89+

‎docs/search/search/collapsing/field-collapse-usage.asciidoc‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/5.0
2+
3+
:github: https://github.com/elastic/elasticsearch-net
4+
5+
:nuget: https://www.nuget.org/packages
6+
7+
////
8+
IMPORTANT NOTE
9+
==============
10+
This file has been generated from https://github.com/elastic/elasticsearch-net/tree/5.x/src/Tests/Search/Search/Collapsing/FieldCollapseUsageTests.cs.
11+
If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file,
12+
please modify the original csharp file found at the link and submit the PR with that change. Thanks!
13+
////
14+
15+
[[field-collapse-usage]]
16+
== Field Collapse Usage
17+
18+
=== Fluent DSL Example
19+
20+
[source,csharp]
21+
----
22+
s => s
23+
.Collapse(c => c
24+
.Field(f => f.State)
25+
.MaxConcurrentGroupSearches(1000)
26+
.InnerHits(i => i
27+
.Name(nameof(StateOfBeing).ToLowerInvariant())
28+
.Size(5)
29+
.From(1)
30+
)
31+
)
32+
----
33+
34+
=== Object Initializer Syntax Example
35+
36+
[source,csharp]
37+
----
38+
new SearchRequest<Project>
39+
{
40+
Collapse = new FieldCollapse
41+
{
42+
Field = Field<Project>(p => p.State),
43+
MaxConcurrentGroupSearches = 1000,
44+
InnerHits = new InnerHits
45+
{
46+
Name = nameof(StateOfBeing).ToLowerInvariant(),
47+
Size = 5,
48+
From = 1
49+
}
50+
}
51+
}
52+
----
53+
54+
[source,javascript]
55+
.Example json output
56+
----
57+
{
58+
"collapse": {
59+
"field": "state",
60+
"max_concurrent_group_searches": 1000,
61+
"inner_hits": {
62+
"from": 1,
63+
"name": "stateofbeing",
64+
"size": 5
65+
}
66+
}
67+
}
68+
----
69+
70+
=== Handling Responses
71+
72+
[source,csharp]
73+
----
74+
var numberOfStates = Enum.GetValues(typeof(StateOfBeing)).Length;
75+
response.HitsMetaData.Total.Should().BeGreaterThan(numberOfStates);
76+
response.Hits.Count.Should().Be(numberOfStates);
77+
78+
foreach (var hit in response.Hits)
79+
{
80+
var name = nameof(StateOfBeing).ToLowerInvariant();
81+
hit.InnerHits.Should().NotBeNull().And.ContainKey(name);
82+
var innherHits = hit.InnerHits[name];
83+
innherHits.Hits.Total.Should().BeGreaterThan(0);
84+
}
85+
----
86+

‎src/CodeGeneration/ApiGenerator/ApiGenerator.cs‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,8 +56,8 @@ private static RestApiSpec CreateRestApiSpecModel(string downloadBranch, string[
5656
{
5757
foreach (var file in jsonFiles)
5858
{
59-
if (file.EndsWith("_common.json"))
60-
RestApiSpec.CommonApiQueryParameters = CreateCommonApiQueryParameters(file);
59+
if (file.EndsWith("_common.json")) RestApiSpec.CommonApiQueryParameters = CreateCommonApiQueryParameters(file);
60+
else if (file.EndsWith(".obsolete.json")) continue;
6161
else
6262
{
6363
var endpoint = CreateApiEndpoint(file);
@@ -86,9 +86,22 @@ private static KeyValuePair<string, ApiEndpoint> CreateApiEndpoint(string jsonFi
8686
var json = File.ReadAllText(jsonFile);
8787
var endpoint = JsonConvert.DeserializeObject<Dictionary<string, ApiEndpoint>>(json).First();
8888
endpoint.Value.CsharpMethodName = CreateMethodName(endpoint.Key);
89+
PatchObsoleteValues(jsonFile, endpoint.Value);
8990
return endpoint;
9091
}
9192

93+
private static void PatchObsoleteValues(string jsonFile, ApiEndpoint endpoint)
94+
{
95+
var directory = Path.GetDirectoryName(jsonFile);
96+
var obsoleteFile = Path.Combine(directory, Path.GetFileNameWithoutExtension(jsonFile)) + ".obsolete.json";
97+
if (!File.Exists(obsoleteFile)) return;
98+
99+
var json = File.ReadAllText(obsoleteFile);
100+
var endpointOverride = JsonConvert.DeserializeObject<Dictionary<string, ApiEndpoint>>(json).First();
101+
endpoint.ObsoleteQueryParameters = endpointOverride.Value?.Url?.Params ?? new Dictionary<string, ApiQueryParameters>();
102+
endpoint.RemovedMethods = endpointOverride.Value?.RemovedMethods ?? new Dictionary<string, string>();
103+
}
104+
92105
private static Dictionary<string, ApiQueryParameters> CreateCommonApiQueryParameters(string jsonFile)
93106
{
94107
var json = File.ReadAllText(jsonFile);

‎src/CodeGeneration/ApiGenerator/ApiGenerator.csproj‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@
3939
<Paket>True</Paket>
4040
</Content>
4141
<Content Include="RestSpecification\Core\root.html" />
42-
<Content Include="RestSpecification\DeleteByQuery\root.html" />
42+
<Content Include="RestSpecification\Core\_common.json" />
4343
<Reference Include="System" />
4444
<Reference Include="System.Core" />
4545
<Reference Include="System.Xml.Linq" />
@@ -104,6 +104,7 @@
104104
<None Include="RestSpecification\Core\cat.tasks.json" />
105105
<None Include="RestSpecification\Core\cat.templates.json" />
106106
<None Include="RestSpecification\Core\cat.thread_pool.json" />
107+
<None Include="RestSpecification\Core\cat.thread_pool.obsolete.json" />
107108
<None Include="RestSpecification\Core\clear_scroll.json" />
108109
<None Include="RestSpecification\Core\cluster.allocation_explain.json" />
109110
<None Include="RestSpecification\Core\cluster.get_settings.json" />
@@ -114,14 +115,17 @@
114115
<None Include="RestSpecification\Core\cluster.state.json" />
115116
<None Include="RestSpecification\Core\cluster.stats.json" />
116117
<None Include="RestSpecification\Core\count.json" />
118+
<None Include="RestSpecification\Core\count.obsolete.json" />
117119
<None Include="RestSpecification\Core\count_percolate.json" />
118120
<None Include="RestSpecification\Core\create.json" />
119121
<None Include="RestSpecification\Core\delete.json" />
120122
<None Include="RestSpecification\Core\delete_by_query.json" />
123+
<None Include="RestSpecification\Core\delete_by_query.obsolete.json" />
121124
<None Include="RestSpecification\Core\delete_script.json" />
122125
<None Include="RestSpecification\Core\delete_template.json" />
123126
<None Include="RestSpecification\Core\exists.json" />
124127
<None Include="RestSpecification\Core\explain.json" />
128+
<None Include="RestSpecification\Core\explain.obsolete.json" />
125129
<None Include="RestSpecification\Core\field_stats.json" />
126130
<None Include="RestSpecification\Core\get.json" />
127131
<None Include="RestSpecification\Core\get_script.json" />
@@ -137,6 +141,7 @@
137141
<None Include="RestSpecification\Core\indices.delete_template.json" />
138142
<None Include="RestSpecification\Core\indices.exists.json" />
139143
<None Include="RestSpecification\Core\indices.exists_alias.json" />
144+
<None Include="RestSpecification\Core\indices.exists_alias.obsolete.json" />
140145
<None Include="RestSpecification\Core\indices.exists_template.json" />
141146
<None Include="RestSpecification\Core\indices.exists_type.json" />
142147
<None Include="RestSpecification\Core\indices.flush.json" />
@@ -164,6 +169,7 @@
164169
<None Include="RestSpecification\Core\indices.update_aliases.json" />
165170
<None Include="RestSpecification\Core\indices.upgrade.json" />
166171
<None Include="RestSpecification\Core\indices.validate_query.json" />
172+
<None Include="RestSpecification\Core\indices.validate_query.obsolete.json" />
167173
<None Include="RestSpecification\Core\info.json" />
168174
<None Include="RestSpecification\Core\ingest.delete_pipeline.json" />
169175
<None Include="RestSpecification\Core\ingest.get_pipeline.json" />
@@ -186,6 +192,7 @@
186192
<None Include="RestSpecification\Core\render_search_template.json" />
187193
<None Include="RestSpecification\Core\scroll.json" />
188194
<None Include="RestSpecification\Core\search.json" />
195+
<None Include="RestSpecification\Core\search.obsolete.json" />
189196
<None Include="RestSpecification\Core\search_shards.json" />
190197
<None Include="RestSpecification\Core\search_template.json" />
191198
<None Include="RestSpecification\Core\snapshot.create.json" />
@@ -198,13 +205,14 @@
198205
<None Include="RestSpecification\Core\snapshot.status.json" />
199206
<None Include="RestSpecification\Core\snapshot.verify_repository.json" />
200207
<None Include="RestSpecification\Core\suggest.json" />
208+
<None Include="RestSpecification\Core\suggest.obsolete.json" />
201209
<None Include="RestSpecification\Core\tasks.cancel.json" />
202210
<None Include="RestSpecification\Core\tasks.get.json" />
203211
<None Include="RestSpecification\Core\tasks.list.json" />
204212
<None Include="RestSpecification\Core\termvectors.json" />
205213
<None Include="RestSpecification\Core\update.json" />
206214
<None Include="RestSpecification\Core\update_by_query.json" />
207-
<None Include="RestSpecification\DeleteByQuery\delete_by_query.json" />
215+
<None Include="RestSpecification\Core\update_by_query.obsolete.json" />
208216
<None Include="RestSpecification\XPack\Graph\xpack.graph.explore.json" />
209217
<None Include="RestSpecification\XPack\License\xpack.license.delete.json" />
210218
<None Include="RestSpecification\XPack\License\xpack.license.get.json" />

0 commit comments

Comments
 (0)