[DOCS] Reformat create index API docs (#45749)

docs/reference/indices/create-index.asciidoc

@@ -1,43 +1,98 @@
 [[indices-create-index]]
-=== Create Index
+=== Create index API
+++++
+<titleabbrev>Create index</titleabbrev>
+++++
 
-The Create Index API is used to manually create an index in Elasticsearch.  All documents in Elasticsearch
-are stored inside of one index or another.
-
-The most basic command is the following:
+Creates a new index.
 
 [source,js]
 --------------------------------------------------
-PUT twitter
+PUT /twitter
 --------------------------------------------------
 // CONSOLE
 
-This creates an index named `twitter` with all default setting.
 
-[NOTE]
-.Index name limitations
-======================================================
-There are several limitations to what you can name your index.  The complete list of limitations are:
+[[indices-create-api-request]]
+==== {api-request-title}
+
+`PUT /<index>`
+
+[[indices-create-api-desc]]
+==== {api-description-title}
+You can use the create index API to add a new index to an {es} cluster. When 
+creating an index, you can specify the following:
+
+* Settings for the index
+* Mappings for fields in the index
+* Index aliases
+
+
+[[indices-create-api-path-params]]
+==== {api-path-parms-title}
+
+`<index>`::
++
+--
+(Optional, string) Name of the index you wish to create.
+
+Index names must meet the following criteria:
 
 - Lowercase only
 - Cannot include `\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, ` ` (space character), `,`, `#`
 - Indices prior to 7.0 could contain a colon (`:`), but that's been deprecated and won't be supported in 7.0+
 - Cannot start with `-`, `_`, `+`
 - Cannot be `.` or `..`
 - Cannot be longer than 255 bytes (note it is bytes, so multi-byte characters will count towards the 255 limit faster)
+--
+
+
+[[indices-create-api-query-params]]
+==== {api-query-parms-title}
 
-======================================================
+include::{docdir}/rest-api/common-parms.asciidoc[tag=include-type-name]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-wait-for-active-shards]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
+
+
+[[indices-create-api-request-body]]
+==== {api-request-body-title}
+
+`aliases`::
+(Optional, <<indices-aliases,alias object>>) Index aliases which include the
+index. See <<indices-aliases>>.
+
+`mappings`::
++
+--
+(Optional, <<mapping,mapping object>>) Mapping for fields in the index. If
+specified, this mapping can include:
+
+* Field names
+* <<mapping-types,Field datatypes>>
+* <<mapping-params,Mapping parameters>>
+
+See <<mapping>>.
+--
+
+`settings`::
+(Optional, <<index-modules-settings,index setting object>>) Configuration
+options for the index. See <<index-modules-settings>>.
+
+[[indices-create-api-example]]
+==== {api-examples-title}
 
-[float]
 [[create-index-settings]]
-==== Index Settings
+===== Index settings
 
 Each index created can have specific settings
 associated with it, defined in the body:
 
 [source,js]
 --------------------------------------------------
-PUT twitter
+PUT /twitter
 {
     "settings" : {
         "index" : {
@@ -55,7 +110,7 @@ or more simplified
 
 [source,js]
 --------------------------------------------------
-PUT twitter
+PUT /twitter
 {
     "settings" : {
         "number_of_shards" : 3,
@@ -73,16 +128,14 @@ For more information regarding all the different index level settings
 that can be set when creating an index, please check the
 <<index-modules,index modules>> section.
 
-
-[float]
 [[mappings]]
-==== Mappings
+===== Mappings
 
 The create index API allows for providing a mapping definition:
 
 [source,js]
 --------------------------------------------------
-PUT test
+PUT /test
 {
     "settings" : {
         "number_of_shards" : 1
@@ -100,15 +153,14 @@ NOTE: Before 7.0.0, the 'mappings' definition used to include a type name. Altho
 types in requests is now deprecated, a type can still be provided if the request parameter
 include_type_name is set. For more details, please see <<removal-of-types>>.
 
-[float]
 [[create-index-aliases]]
-==== Aliases
+===== Aliases
 
 The create index API allows also to provide a set of <<indices-aliases,aliases>>:
 
 [source,js]
 --------------------------------------------------
-PUT test
+PUT /test
 {
     "aliases" : {
         "alias_1" : {},
@@ -123,9 +175,8 @@ PUT test
 --------------------------------------------------
 // CONSOLE
 
-[float]
 [[create-index-wait-for-active-shards]]
-==== Wait For Active Shards
+===== Wait For active shards
 
 By default, index creation will only return a response to the client when the primary copies of
 each shard have been started, or the request times out. The index creation response will indicate
@@ -158,7 +209,7 @@ the `wait_for_active_shards` value on all subsequent write operations):
 
 [source,js]
 --------------------------------------------------
-PUT test
+PUT /test
 {
     "settings": {
         "index.write.wait_for_active_shards": "2"
@@ -172,7 +223,7 @@ or through the request parameter `wait_for_active_shards`:
 
 [source,js]
 --------------------------------------------------
-PUT test?wait_for_active_shards=2
+PUT /test?wait_for_active_shards=2
 --------------------------------------------------
 // CONSOLE
 // TEST[skip:requires two nodes]

docs/reference/rest-api/common-parms.asciidoc

@@ -163,10 +163,15 @@ end::doc-version-type[]
 
 tag::doc-wait-for-active-shards[]
 `wait_for_active_shards`::
++
+--
 (Optional, string) The number of shard copies that must be active before
 proceeding with the operation. Set to `all` or any positive integer up
 to the total number of shards in the index (`number_of_replicas+1`).
 Default: 1, the primary shard.
+
+See <<index-wait-for-active-shards>>.
+--
 end::doc-wait-for-active-shards[]
 
 tag::timeoutparms[]