From 4cfff1a5ff27ebb021e49ba0802f749411bdd447 Mon Sep 17 00:00:00 2001 From: Jorge Date: Sat, 7 Aug 2021 20:03:55 +0200 Subject: [PATCH] docs: update documentation --- docs/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index eb2da07..08ff2f7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -382,7 +382,7 @@ This library automatically transform query and headers parameters from Postman o The default schema used for parameters is `string` but the library try to infer the type of the parameters based on the value using regular expressions, the detected types are `integer`, `number`, `boolean` and `string`, if you find any problem in the inference process please open an issue. -Path parameters are also automatically detected, this library look for [Postman variables](https://learning.postman.com/docs/sending-requests/variables/) in the url as "{{variable}}" and transform to a single curly brace expression as `{variable}` as supported by OpenAPI, also create the parameter definition using the variable name. To provide additional information about a path parameter you can [Pass Meta-information as markdown](#pass-meta-information-as-markdown). Be aware that if you use the `replaceVar` option the path parameter using Postman variables can be affected. See [replaceVars option](#replacevars-boolean) +This library now support the definition of path parameters using the postman notation defined in [sending parameters](https://learning.postman.com/docs/sending-requests/requests/#sending-parameters),what basically consist in annotate params with a semicolon as for example `/customer/:id`, when postman detect this notation a new form appear in the request to define value and description of the parameters. This is the preferred way to define path parameters in a postman collection but also path parameters are automatically detected as postman variables, this library look for [Postman variables](https://learning.postman.com/docs/sending-requests/variables/) in the url as "{{variable}}" and transform to a single curly brace expression as `{variable}` as supported by OpenAPI, also create the parameter definition using the variable name. To provide additional information about a path parameter you can [Pass Meta-information as markdown](#pass-meta-information-as-markdown). Be aware that if you use the `replaceVar` option the path parameter using Postman variables can be affected. See [replaceVars option](#replacevars-boolean) For headers and query fields you can indicate that this parameter is mandatory/required adding into the description the literal `[required]`. The library use a case insensitive regexp so all variations are supported (`[REQUIRED]`, `[Required]`...) and never mind the location inside the description (at the beginning, at the end...). @@ -424,6 +424,8 @@ You can also customize this information using the [Info option](#info-(object)), ## Pass Meta-information as markdown +> Note: postman already provide a way to define path variables that is recommended over use this solution, take into account that "Meta-information as markdown" would be probably deprecated in the future. + As Postman don't provide a free way to pass meta information in all the sections, for example you cannot describe a Path parameter in Postman, the easy way we have found is to provide this information in the `options` parameter when calling the library, although this solution is not a bad solution, and give lot of freedom about where you store the info, we think that have all the info about the API in the Postman Collection is the best solution as you only have a source of information for document your APIs. That's the reason why API `version` can be defined as a postman collection variable, as described in [Basic API Info](#basic-api-info) section, but for some other information as for example describing a Path parameter where you should indicate multiples values as the description, if it is required, an example, schema type.... the solution of use collection variables don't fit too well, for this reason we have add support for provide Meta-Information as a markdown table.