diff --git a/__tests__/commands/openapi/__snapshots__/inspect.test.ts.snap b/__tests__/commands/openapi/__snapshots__/inspect.test.ts.snap index a26aab331..3ebd1e77a 100644 --- a/__tests__/commands/openapi/__snapshots__/inspect.test.ts.snap +++ b/__tests__/commands/openapi/__snapshots__/inspect.test.ts.snap @@ -139,6 +139,13 @@ x-readme.proxy-enabled: You do not use this. x-readme.samples-languages: You do not use this." `; +exports[`rdme openapi inspect > feature reports > should generate a report for '@readme/oas-examples/3.1/json/train-tโ€ฆ' (w/ [ 'commonParameters' ]) 1`] = ` +" +commonParameters: + ยท #/paths/~1bookings~1{bookingId}/parameters + ยท #/paths/~1bookings~1{bookingId}~1payment/parameters" +`; + exports[`rdme openapi inspect > full reports > should generate a report for @readme/oas-examples/3.0/json/petstore.json 1`] = ` "Here are some interesting things we found in your API definition. ๐Ÿ•ต๏ธ @@ -165,6 +172,12 @@ OpenAPI Features โ”‚ circularRefs โ”‚ โ”‚ Circular references are $ref pointers that at some point in their lineage โ”‚ โ”‚ โ”‚ โ”‚ reference themselves. โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ commonParameters โ”‚ โ”‚ Common parameters allow you to define parameters that are shared across multiple โ”‚ +โ”‚ โ”‚ โ”‚ operations within your API. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#path- โ”‚ +โ”‚ โ”‚ โ”‚ item-object โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ discriminators โ”‚ โ”‚ With schemas that can be, or contain, different shapes, discriminators help you โ”‚ โ”‚ โ”‚ โ”‚ assist your users in identifying and determining the kind of shape they can โ”‚ โ”‚ โ”‚ โ”‚ supply or receive. โ”‚ @@ -275,6 +288,12 @@ OpenAPI Features โ”‚ circularRefs โ”‚ โ”‚ Circular references are $ref pointers that at some point in their lineage โ”‚ โ”‚ โ”‚ โ”‚ reference themselves. โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ commonParameters โ”‚ โ”‚ Common parameters allow you to define parameters that are shared across multiple โ”‚ +โ”‚ โ”‚ โ”‚ operations within your API. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#path- โ”‚ +โ”‚ โ”‚ โ”‚ item-object โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ discriminators โ”‚ โ”‚ With schemas that can be, or contain, different shapes, discriminators help you โ”‚ โ”‚ โ”‚ โ”‚ assist your users in identifying and determining the kind of shape they can โ”‚ โ”‚ โ”‚ โ”‚ supply or receive. โ”‚ @@ -385,6 +404,12 @@ OpenAPI Features โ”‚ circularRefs โ”‚ โ”‚ Circular references are $ref pointers that at some point in their lineage โ”‚ โ”‚ โ”‚ โ”‚ reference themselves. โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ commonParameters โ”‚ โ”‚ Common parameters allow you to define parameters that are shared across multiple โ”‚ +โ”‚ โ”‚ โ”‚ operations within your API. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#path- โ”‚ +โ”‚ โ”‚ โ”‚ item-object โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ discriminators โ”‚ โ”‚ With schemas that can be, or contain, different shapes, discriminators help you โ”‚ โ”‚ โ”‚ โ”‚ assist your users in identifying and determining the kind of shape they can โ”‚ โ”‚ โ”‚ โ”‚ supply or receive. โ”‚ @@ -468,3 +493,119 @@ ReadMe-Specific Features and Extensions โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ " `; + +exports[`rdme openapi inspect > full reports > should generate a report for @readme/oas-examples/3.1/json/train-travel.json 1`] = ` +"Here are some interesting things we found in your API definition. ๐Ÿ•ต๏ธ + + ยท You are using 2 Media Types throughout your API: application/json and application/xml + ยท You have a total of 9 Operations in your API. + ยท You are using a single Security Type throughout your API: oauth2 + +OpenAPI Features +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Feature โ”‚ Used? โ”‚ Description โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ additionalProperties โ”‚ โ”‚ additionalProperties allows you to document dictionaries where the keys are โ”‚ +โ”‚ โ”‚ โ”‚ user-supplied strings. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://json-schema.org/understanding-json-schema/reference/object. โ”‚ +โ”‚ โ”‚ โ”‚ html#additional-properties โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ callbacks โ”‚ โ”‚ Callbacks are asynchronous, out-of-band requests that your service will send to โ”‚ +โ”‚ โ”‚ โ”‚ some other service in response to certain events. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0. โ”‚ +โ”‚ โ”‚ โ”‚ md#callback-object โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ circularRefs โ”‚ โ”‚ Circular references are $ref pointers that at some point in their lineage โ”‚ +โ”‚ โ”‚ โ”‚ reference themselves. โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ commonParameters โ”‚ โœ… โ”‚ Common parameters allow you to define parameters that are shared across multiple โ”‚ +โ”‚ โ”‚ โ”‚ operations within your API. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#path- โ”‚ +โ”‚ โ”‚ โ”‚ item-object โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ discriminators โ”‚ โ”‚ With schemas that can be, or contain, different shapes, discriminators help you โ”‚ +โ”‚ โ”‚ โ”‚ assist your users in identifying and determining the kind of shape they can โ”‚ +โ”‚ โ”‚ โ”‚ supply or receive. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0. โ”‚ +โ”‚ โ”‚ โ”‚ md#discriminator-object โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ links โ”‚ โœ… โ”‚ Links allow you to define at call-time relationships to other operations within โ”‚ +โ”‚ โ”‚ โ”‚ your API. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#link- โ”‚ +โ”‚ โ”‚ โ”‚ object โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ style โ”‚ โ”‚ Parameter serialization (style) allows you to describe how the parameter should โ”‚ +โ”‚ โ”‚ โ”‚ be sent to your API. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0. โ”‚ +โ”‚ โ”‚ โ”‚ md#parameter-style โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ polymorphism โ”‚ โœ… โ”‚ Polymorphism (allOf, oneOf, and anyOf) allow you to describe schemas that may โ”‚ +โ”‚ โ”‚ โ”‚ contain either many different shapes, or a single shape containing multiple โ”‚ +โ”‚ โ”‚ โ”‚ different schemas. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://json-schema.org/understanding-json-schema/reference/combining.html โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ serverVariables โ”‚ โ”‚ Server variables allow to do user-supplied variable subsitituions within your โ”‚ +โ”‚ โ”‚ โ”‚ API server URL. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#server- โ”‚ +โ”‚ โ”‚ โ”‚ variable-object โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ webhooks โ”‚ โœ… โ”‚ Webhooks allow you to describe out of band requests that may be initiated by โ”‚ +โ”‚ โ”‚ โ”‚ your users. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#user- โ”‚ +โ”‚ โ”‚ โ”‚ content-oaswebhooks โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ xml โ”‚ โœ… โ”‚ Any parameter and/or request body that accepts XML or responses that return XML โ”‚ +โ”‚ โ”‚ โ”‚ payloads. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#xml- โ”‚ +โ”‚ โ”‚ โ”‚ object โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + + +ReadMe-Specific Features and Extensions +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Feature โ”‚ Used? โ”‚ Description โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ x-default โ”‚ โ”‚ The x-default extension allows you to define static authentication credential โ”‚ +โ”‚ โ”‚ โ”‚ defaults for OAuth 2 and API Key security types. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://docs.readme.com/main/docs/openapi-extensions#authentication-defaults โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ x-readme.code-samples โ”‚ โ”‚ The x-readme.code-samples extension allows you to custom, create static code โ”‚ +โ”‚ โ”‚ โ”‚ samples on your API documentation. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://docs.readme.com/main/docs/openapi-extensions#custom-code-samples โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ x-readme.headers โ”‚ โ”‚ The x-readme.headers extension allows you define headers that should always be โ”‚ +โ”‚ โ”‚ โ”‚ present on your API or a specific operation, as well as what its value should โ”‚ +โ”‚ โ”‚ โ”‚ be. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://docs.readme.com/main/docs/openapi-extensions#static-headers โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ x-readme.explorer-enabled โ”‚ โ”‚ The x-readme.explorer-enabled extension allows you to toggle your API โ”‚ +โ”‚ โ”‚ โ”‚ documentation being interactive or not. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://docs.readme.com/main/docs/openapi-extensions#disable-the-api-explorer โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ x-readme.proxy-enabled โ”‚ โ”‚ The x-readme.proxy-enabled extension allows you to toggle if API requests from โ”‚ +โ”‚ โ”‚ โ”‚ API documentation should be routed through ReadMe's CORS Proxy. You should only โ”‚ +โ”‚ โ”‚ โ”‚ need to use this if your API does not support CORS. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://docs.readme.com/main/docs/openapi-extensions#cors-proxy-enabled โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ x-readme.samples-languages โ”‚ โ”‚ The x-readme.samples-languages extension allows you to toggle what languages are โ”‚ +โ”‚ โ”‚ โ”‚ shown by default for code snippets in your API documentation. โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ https://docs.readme.com/main/docs/openapi-extensions#code-sample-languages โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +" +`; diff --git a/__tests__/commands/openapi/inspect.test.ts b/__tests__/commands/openapi/inspect.test.ts index c5a0137f2..228bd668a 100644 --- a/__tests__/commands/openapi/inspect.test.ts +++ b/__tests__/commands/openapi/inspect.test.ts @@ -19,6 +19,7 @@ describe('rdme openapi inspect', () => { '@readme/oas-examples/3.0/json/petstore.json', '@readme/oas-examples/3.0/json/readme.json', '@readme/oas-examples/3.0/json/readme-extensions.json', + '@readme/oas-examples/3.1/json/train-travel.json', ])('should generate a report for %s', spec => { return expect(run([require.resolve(spec)])).resolves.toMatchSnapshot(); }); @@ -42,6 +43,10 @@ describe('rdme openapi inspect', () => { spec: '@readme/oas-examples/3.0/json/schema-circular.json', feature: ['additionalProperties', 'circularRefs'], }, + { + spec: '@readme/oas-examples/3.1/json/train-travel.json', + feature: ['commonParameters'], + }, // Soft error cases where we may or may not contain the features we're querying for. { diff --git a/__tests__/lib/__snapshots__/analyzeOas.test.ts.snap b/__tests__/lib/__snapshots__/analyzeOas.test.ts.snap index fdfc4c0e0..6ec1a16ec 100644 --- a/__tests__/lib/__snapshots__/analyzeOas.test.ts.snap +++ b/__tests__/lib/__snapshots__/analyzeOas.test.ts.snap @@ -50,6 +50,15 @@ exports[`#analyzeOas > should analyze an OpenAPI definition 1`] = ` "locations": [], "present": false, }, + "commonParameters": { + "description": "Common parameters allow you to define parameters that are shared across multiple operations within your API.", + "locations": [], + "present": false, + "url": { + "3.0": "https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#path-item-object", + "3.1": "https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#path-item-object", + }, + }, "discriminators": { "description": "With schemas that can be, or contain, different shapes, discriminators help you assist your users in identifying and determining the kind of shape they can supply or receive.", "locations": [], @@ -135,6 +144,12 @@ exports[`#analyzeOas > should analyze an OpenAPI definition 1`] = ` "present": false, "url": "https://docs.readme.com/main/docs/openapi-extensions#authentication-defaults", }, + "x-readme-ref-name": { + "description": "x-readme-ref-name is added by our tooling after dereferencing in order to preserve original reference schema names.", + "hidden": true, + "locations": [], + "present": false, + }, "x-readme.code-samples": { "description": "The x-readme.code-samples extension allows you to custom, create static code samples on your API documentation.", "locations": [], diff --git a/__tests__/lib/analyzeOas.test.ts b/__tests__/lib/analyzeOas.test.ts index 61ebe82fd..8e5495305 100644 --- a/__tests__/lib/analyzeOas.test.ts +++ b/__tests__/lib/analyzeOas.test.ts @@ -19,6 +19,7 @@ describe('#getSupportedFeatures', () => { 'additionalProperties', 'callbacks', 'circularRefs', + 'commonParameters', 'discriminators', 'links', 'style', diff --git a/package-lock.json b/package-lock.json index f829dae2f..98c70281f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -22,10 +22,9 @@ "gray-matter": "^4.0.1", "ignore": "^6.0.2", "mime-types": "^2.1.35", - "oas": "^25.0.0", - "oas-normalize": "^11.1.2", + "oas": "^25.2.1", + "oas-normalize": "^12.0.0", "ora": "^8.1.1", - "pluralize": "^8.0.0", "prompts": "^2.4.2", "semver": "^7.5.3", "simple-git": "^3.19.1", @@ -56,7 +55,6 @@ "@types/debug": "^4.1.7", "@types/js-yaml": "^4.0.5", "@types/mime-types": "^2.1.1", - "@types/pluralize": "^0.0.33", "@types/prompts": "^2.4.2", "@types/semver": "^7.3.12", "@types/toposort": "^2.0.7", @@ -4417,13 +4415,6 @@ "dev": true, "license": "MIT" }, - "node_modules/@types/pluralize": { - "version": "0.0.33", - "resolved": "https://registry.npmjs.org/@types/pluralize/-/pluralize-0.0.33.tgz", - "integrity": "sha512-JOqsl+ZoCpP4e8TDke9W79FDcSgPAR0l6pixx2JHkhnRjvShyYiAYw2LVsnA7K08Y6DeOnaU6ujmENO4os/cYg==", - "dev": true, - "license": "MIT" - }, "node_modules/@types/prompts": { "version": "2.4.9", "resolved": "https://registry.npmjs.org/@types/prompts/-/prompts-2.4.9.tgz", @@ -13437,9 +13428,9 @@ } }, "node_modules/oas": { - "version": "25.0.4", - "resolved": "https://registry.npmjs.org/oas/-/oas-25.0.4.tgz", - "integrity": "sha512-7xVFOBPB4VJM+RLnxbNdmUsr2y9ExLfSgy7+zDzkHKTWEPaPsRPp6PBRZ78OeOmO8d9T23sjLisNWR7N7/Ue7Q==", + "version": "25.2.1", + "resolved": "https://registry.npmjs.org/oas/-/oas-25.2.1.tgz", + "integrity": "sha512-56NO/ThEzIQeniJHm12tFIIGaugcdZTxYWiWP0KV8W9DcdWRvk9tvBEKITFp9r62w7W25vobedpiApa9u/Aoxg==", "license": "MIT", "dependencies": { "@readme/json-schema-ref-parser": "^1.2.0", @@ -13448,7 +13439,6 @@ "jsonpath-plus": "^10.0.0", "jsonpointer": "^5.0.0", "memoizee": "^0.4.16", - "oas-normalize": "^11.1.4", "openapi-types": "^12.1.1", "path-to-regexp": "^8.1.0", "remove-undefined-objects": "^5.0.0" @@ -13481,9 +13471,9 @@ } }, "node_modules/oas-normalize": { - "version": "11.1.4", - "resolved": "https://registry.npmjs.org/oas-normalize/-/oas-normalize-11.1.4.tgz", - "integrity": "sha512-K533PwDAvm3KtugGu4H/GtHrIrEbFRoLkT8fLY6PU+m80JxzhbVKG8eUJUHwr3NesTt8VSA6O2r6eBcdqkRe2A==", + "version": "12.0.0", + "resolved": "https://registry.npmjs.org/oas-normalize/-/oas-normalize-12.0.0.tgz", + "integrity": "sha512-MTPCpmmpApMFHvDMYrUQT6j1EY6pAp+Wodg7z95uOW9LICSpbkiE1gB7YeU1YJep9VTIH5X/SiwfnTXnlC+ShA==", "license": "MIT", "dependencies": { "@readme/openapi-parser": "^2.6.0", @@ -14473,6 +14463,7 @@ "version": "8.0.0", "resolved": "https://registry.npmjs.org/pluralize/-/pluralize-8.0.0.tgz", "integrity": "sha512-Nc3IT5yHzflTfbjgqWcCPpo7DaKy4FnpB0l/zCAW0Tc7jxAiuqSxHasntB3D7887LSrA93kDJ9IXovxJYxyLCA==", + "dev": true, "license": "MIT", "engines": { "node": ">=4" diff --git a/package.json b/package.json index 9d1c28a76..a61a320e2 100644 --- a/package.json +++ b/package.json @@ -54,10 +54,9 @@ "gray-matter": "^4.0.1", "ignore": "^6.0.2", "mime-types": "^2.1.35", - "oas": "^25.0.0", - "oas-normalize": "^11.1.2", + "oas": "^25.2.1", + "oas-normalize": "^12.0.0", "ora": "^8.1.1", - "pluralize": "^8.0.0", "prompts": "^2.4.2", "semver": "^7.5.3", "simple-git": "^3.19.1", @@ -85,7 +84,6 @@ "@types/debug": "^4.1.7", "@types/js-yaml": "^4.0.5", "@types/mime-types": "^2.1.1", - "@types/pluralize": "^0.0.33", "@types/prompts": "^2.4.2", "@types/semver": "^7.3.12", "@types/toposort": "^2.0.7", diff --git a/src/commands/openapi/convert.ts b/src/commands/openapi/convert.ts index 51ca5d922..9ef049f5f 100644 --- a/src/commands/openapi/convert.ts +++ b/src/commands/openapi/convert.ts @@ -54,7 +54,6 @@ export default class OpenAPIConvertCommand extends BaseCommand 1 ? `${str}s` : str; +} + function getFeatureDocsURL(feature: AnalyzedFeature, definitionVersion: string): string | undefined { if (!feature.url) { return undefined; @@ -68,6 +71,10 @@ function buildFeaturesReport(analysis: Analysis, features: string[]) { } Object.entries(analysis.readme).forEach(([feature, info]) => { + if (info.hidden) { + return; + } + if (!info.present) { report.push(`${feature}: You do not use this.`); hasUnusedFeature = true; @@ -140,6 +147,10 @@ function buildFullReport(analysis: Analysis, definitionVersion: string, tableBor ]; Object.entries(analysis[component as 'openapi' | 'readme']).forEach(([feature, info]) => { + if (info.hidden) { + return; + } + const descriptions: string[] = []; if (info.description) { descriptions.push(info.description); @@ -224,7 +235,7 @@ export default class OpenAPIInspectCommand extends BaseCommand> = { +const README_FEATURE_DOCS: Record> = { 'x-default': { description: 'The x-default extension allows you to define static authentication credential defaults for OAuth 2 and API Key security types.', url: 'https://docs.readme.com/main/docs/openapi-extensions#authentication-defaults', }, + 'x-readme-ref-name': { + description: + 'x-readme-ref-name is added by our tooling after dereferencing in order to preserve original reference schema names.', + hidden: true, + }, 'x-readme.code-samples': { description: 'The x-readme.code-samples extension allows you to custom, create static code samples on your API documentation.', diff --git a/src/lib/prepareOas.ts b/src/lib/prepareOas.ts index 555bc0a88..37ba24926 100644 --- a/src/lib/prepareOas.ts +++ b/src/lib/prepareOas.ts @@ -51,18 +51,12 @@ export default async function prepareOas( path: string | undefined, command: 'openapi convert' | 'openapi inspect' | 'openapi reduce' | 'openapi validate' | 'openapi', opts: { - /** - * Optionally convert the supplied or discovered API definition to the latest OpenAPI release. - */ - convertToLatest?: boolean; /** * An optional title to replace the value in the `info.title` field. * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#info-object} */ title?: string; - } = { - convertToLatest: false, - }, + } = {}, ) { let specPath = path; @@ -189,12 +183,21 @@ export default async function prepareOas( throw err; }); - // If we were supplied a Postman collection this will **always** convert it to OpenAPI 3.0. - let api: OpenAPI.Document = await oas.validate({ convertToLatest: opts.convertToLatest }).catch((err: Error) => { + let api: OpenAPI.Document; + await oas.validate().catch((err: Error) => { spinner.fail(); debug(`raw validation error object: ${JSON.stringify(err)}`); throw err; }); + + // If we were supplied a Postman collection this will **always** convert it to OpenAPI 3.0. + debug('converting the spec to OpenAPI 3.0 (if necessary)'); + api = await oas.convert().catch((err: Error) => { + spinner.fail(); + debug(`raw openapi conversion error object: ${JSON.stringify(err)}`); + throw err; + }); + spinner.stop(); debug('๐Ÿ‘‡๐Ÿ‘‡๐Ÿ‘‡๐Ÿ‘‡๐Ÿ‘‡ spec validated! logging spec below ๐Ÿ‘‡๐Ÿ‘‡๐Ÿ‘‡๐Ÿ‘‡๐Ÿ‘‡');