[New feature] Render request headers

api-specs/api/package.json

@@ -8,6 +8,6 @@
     "generate-ramldoc:watch": "npx rmf-codegen generate ./api.raml -w -o ../../websites/api-docs-smoke-test/src/api-specs/api -t RAML_DOC"
   },
   "dependencies": {
-    "@commercetools-docs/rmf-codegen": "13.13.0"
+    "@commercetools-docs/rmf-codegen": "13.25.0"
   }
 }

api-specs/test/api.raml

@@ -475,6 +475,43 @@ uses:
                 type: object
                 example: !include examples/action-success.json
 
+    /namespace-action-with-headers:
+      uriParameters:
+        namespace:
+          displayName: Namespace
+          type: string
+          description: The namespace where the action to invoked is located.
+        action:
+          displayName: Action
+          type: string
+          description: The name of the action to invoked.
+      get:
+        headers:
+          Frontastic-Locale:
+            displayName: Frontastic Locale
+            type: string
+            description: Locale
+          Frontastic-Path:
+            displayName: Frontastic Path
+            type: string
+            description: Path
+            required: true
+            pattern: ^/.*$
+          Accept:
+            displayName: Accept Header
+            type: string
+            description: Accept application/json Header
+            required: true
+            pattern: application/json
+            default: application/json
+        description: Use the GET method to allow the frontend to fetch data from a backend system. For the response, we recommend to use standard HTTP codes and `application/json` encoded content. The response will be structured as defined by the body property of the action.
+        responses:
+          200:
+            description: The response will be structured as defined by the body property of the action.
+            body:
+              application/json:
+                type: object
+                example: !include examples/action-success.json
 
 #   /resourceWithHeaders:
 #    description: Tests use of specific headers.

api-specs/test/package.json

@@ -8,6 +8,6 @@
     "generate-ramldoc:watch": "npx rmf-codegen generate ./api.raml -w -o ../../websites/api-docs-smoke-test/src/api-specs/test -t RAML_DOC"
   },
   "dependencies": {
-    "@commercetools-docs/rmf-codegen": "13.13.0"
+    "@commercetools-docs/rmf-codegen": "13.25.0"
   }
 }

packages/gatsby-theme-api-docs/package.json

@@ -34,7 +34,7 @@
     "unist-util-visit": "2.0.3"
   },
   "devDependencies": {
-    "@commercetools-docs/rmf-codegen": "13.13.0",
+    "@commercetools-docs/rmf-codegen": "13.25.0",
     "gatsby": "4.24.4",
     "react": "18.2.0",
     "react-dom": "18.2.0"

packages/gatsby-theme-api-docs/src/components/info.js

@@ -1,12 +1,58 @@
+import React from 'react';
+import PropTypes from 'prop-types';
 import styled from '@emotion/styled';
+import { css } from '@emotion/react';
+import { Markdown, useISO310NumberFormatter } from '@commercetools-docs/ui-kit';
 import { colors, dimensions, typography } from '../design-system';
 
-const Info = styled.span`
+const customCodeStyle = css`
+  border: none;
+  background-color: unset;
+  padding: 0;
+`;
+
+export const Info = styled.span`
   display: inline-block;
   border: 1px solid ${colors.light.borderInfo};
   background-color: ${colors.light.surfaceInfo};
   padding: ${dimensions.spacings.xxs} ${dimensions.spacings.xs};
   font-size: ${typography.fontSizes.small};
 `;
 
-export default Info;
+export const InfoValue = (props) => {
+  const value = props.children;
+  const valueType = typeof value;
+  const formatNumber = useISO310NumberFormatter();
+
+  switch (valueType) {
+    case 'boolean':
+      return value ? (
+        ''
+      ) : (
+        <>
+          : <Markdown.InlineCode css={customCodeStyle}>No</Markdown.InlineCode>
+        </>
+      );
+    case 'number':
+      return (
+        <>
+          :{' '}
+          <Markdown.InlineCode css={customCodeStyle}>
+            {formatNumber(value)}
+          </Markdown.InlineCode>
+        </>
+      );
+    default:
+      return (
+        <>
+          :{' '}
+          <Markdown.InlineCode css={customCodeStyle}>
+            {value}
+          </Markdown.InlineCode>
+        </>
+      );
+  }
+};
+InfoValue.propTypes = {
+  children: PropTypes.any.isRequired,
+};

packages/gatsby-theme-api-docs/src/components/resource/method/headers.js

@@ -0,0 +1,103 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import styled from '@emotion/styled';
+import SpacingsStack from '@commercetools-uikit/spacings-stack';
+import SpacingsInline from '@commercetools-uikit/spacings-inline';
+import {
+  Markdown,
+  designSystem,
+  markdownFragmentToReact,
+} from '@commercetools-docs/ui-kit';
+import { Link as GatsbyLink } from '@commercetools-docs/gatsby-theme-docs';
+import transformURNLinksPlugin from '../../../utils/transform-urn-links-plugin';
+import capitalizeFirst from '../../../utils/capitalize-first';
+import { typography } from '../../../design-system';
+import { Info, InfoValue } from '../../info';
+import Required from '../../required';
+import Table from '../../table';
+import Title from './title';
+
+const PropertyName = styled.div`
+  white-space: nowrap;
+  line-height: ${typography.lineHeights.propertyType};
+`;
+const PropertyType = styled.div`
+  line-height: ${typography.lineHeights.propertyType};
+  color: ${designSystem.colors.light.textFaded};
+`;
+
+const DescriptionTextContainer = styled.span`
+  display: inline-block;
+`;
+
+const Headers = (props) => {
+  console.log(props.headers);
+  return (
+    <SpacingsStack scale="xs">
+      {props.title && <Title>{props.title}:</Title>}
+      <Table>
+        <tbody>
+          {props.headers.map((header, headerIndex) => {
+            return (
+              <tr key={headerIndex}>
+                <td>
+                  <SpacingsStack scale="xs">
+                    <PropertyName>
+                      <SpacingsInline scale="xs">
+                        <Markdown.InlineCode>
+                          {header.displayName
+                            ? header.displayName
+                            : header.header}
+                        </Markdown.InlineCode>
+                        {'\u200B' /* zero-width space for the search crawler */}
+                        {header.required && <Required />}
+                      </SpacingsInline>
+                    </PropertyName>
+                    <PropertyType>
+                      {capitalizeFirst(header.type)}
+                      {'\u200B' /* zero-width space for the search crawler */}
+                    </PropertyType>
+                  </SpacingsStack>
+                </td>
+                <td>
+                  <SpacingsStack scale="xs">
+                    <DescriptionTextContainer data-search-key="embedded-api-description">
+                      {markdownFragmentToReact(
+                        header.description,
+                        { a: GatsbyLink },
+                        transformURNLinksPlugin
+                      )}
+                    </DescriptionTextContainer>
+                    <SpacingsInline>
+                      {header.pattern && (
+                        <Info>
+                          Pattern<InfoValue>{header.pattern}</InfoValue>
+                        </Info>
+                      )}
+                    </SpacingsInline>
+                  </SpacingsStack>
+                </td>
+              </tr>
+            );
+          })}
+        </tbody>
+      </Table>
+    </SpacingsStack>
+  );
+};
+
+Headers.propTypes = {
+  title: PropTypes.string.isRequired,
+  headers: PropTypes.arrayOf(
+    PropTypes.shape({
+      header: PropTypes.string.isRequired,
+      displayName: PropTypes.string,
+      description: PropTypes.string,
+      type: PropTypes.string,
+      required: PropTypes.bool,
+      pattern: PropTypes.string,
+    })
+  ).isRequired,
+};
+
+export default Headers;

packages/gatsby-theme-api-docs/src/components/resource/method/method.js

@@ -13,6 +13,7 @@ import Url from './url';
 import Scopes from './scopes';
 import Responses from './responses';
 import Parameters from './parameters';
+import Headers from './headers';
 import QueryParameters from './query-parameters';
 import RequestRepresentation from './request-representation';
 import { DescriptionParagraph } from '../../description';
@@ -121,6 +122,10 @@ const Method = ({
                 <Scopes scopes={method.securedBy[0].oauth_2_0.scopes} />
               )}
 
+              {method.headers && (
+                <Headers title={'Request headers'} headers={method.headers} />
+              )}
+
               {allUriParameters.length > 0 && (
                 <Parameters
                   title={'Path parameters'}

packages/gatsby-theme-api-docs/src/components/resource/method/parameters.js

@@ -13,7 +13,7 @@ import RegexProperty from '../../type/properties/regex-properties';
 import Table from '../../table';
 import Title from './title';
 import { DescriptionText } from '../../description';
-import Info from '../../info';
+import { Info } from '../../info';
 import { typography } from '../../../design-system';
 
 const isRegex = (string) =>

packages/gatsby-theme-api-docs/src/components/resource/method/responses.js

@@ -52,7 +52,7 @@ const Responses = ({ apiKey, responses, contentType }) => {
                       typeLocations,
                       response.description
                     )}
-                    {contentType.length > 0 && (
+                    {contentType.length > 0 && !response.description && (
                       <>
                         <span>as</span>
                         <ContentType>{contentType}</ContentType>

packages/gatsby-theme-api-docs/src/components/type/properties/rows/description.js

@@ -1,14 +1,14 @@
 import React from 'react';
 import PropTypes from 'prop-types';
 import { css } from '@emotion/react';
-import { Markdown, useISO310NumberFormatter } from '@commercetools-docs/ui-kit';
+import { Markdown } from '@commercetools-docs/ui-kit';
 import SpacingsInline from '@commercetools-uikit/spacings-inline';
 import SpacingsStack from '@commercetools-uikit/spacings-stack';
 import extractAdditionalInfo from '../../../../utils/extract-additional-info';
 import capitalizeFirst from '../../../../utils/capitalize-first';
 import { useApiTypeByApiKeyAndDisplayName } from '../../../../hooks/use-api-types';
 import { DescriptionText } from '../../../description';
-import Info from '../../../info';
+import { Info, InfoValue } from '../../../info';
 
 const customCodeStyle = css`
   border: none;
@@ -60,43 +60,6 @@ ConstantLikeEnumDescription.propTypes = {
   }),
 };
 
-const InfoValue = (props) => {
-  const value = props.children;
-  const valueType = typeof value;
-  const formatNumber = useISO310NumberFormatter();
-
-  switch (valueType) {
-    case 'boolean':
-      return value ? (
-        ''
-      ) : (
-        <>
-          : <Markdown.InlineCode css={customCodeStyle}>No</Markdown.InlineCode>
-        </>
-      );
-    case 'number':
-      return (
-        <>
-          :{' '}
-          <Markdown.InlineCode css={customCodeStyle}>
-            {formatNumber(value)}
-          </Markdown.InlineCode>
-        </>
-      );
-    default:
-      return (
-        <>
-          :{' '}
-          <Markdown.InlineCode css={customCodeStyle}>
-            {value}
-          </Markdown.InlineCode>
-        </>
-      );
-  }
-};
-InfoValue.propTypes = {
-  children: PropTypes.any.isRequired,
-};
 const AdditionalInfo = (props) => {
   const additionalInfos = extractAdditionalInfo(props.property);
   return (

packages/gatsby-theme-api-docs/src/hooks/use-api-resources.js

@@ -25,6 +25,16 @@ export const useApiResources = () => {
             type
           }
         }
+        headers {
+          header
+          displayName
+          default
+          enum
+          description
+          type
+          required
+          pattern
+        }
         responses {
           code
           description

packages/gatsby-transformer-raml/src/schema/define-raml-resource.js

@@ -7,6 +7,7 @@ const defineRamlResource = ({ schema, createTypes }) => {
       description: String
       queryParameters: [RamlResourceQueryParameter!]
       responses: [RamlResourceResponse!]
+      headers: [RamlResourceHeaders!]
       codeExamples: [RamlResourceCodeExample!]
     }
     `,
@@ -51,6 +52,7 @@ const defineRamlResource = ({ schema, createTypes }) => {
         queryParameters: '[RamlResourceQueryParameter!]',
         body: 'RamlResourceMethodBody',
         responses: '[RamlResourceResponse!]',
+        headers: '[RamlResourceHeaders!]',
         codeExamples: '[RamlResourceCodeExample!]',
       },
       interfaces: ['Method'],
@@ -64,6 +66,7 @@ const defineRamlResource = ({ schema, createTypes }) => {
         description: 'String',
         queryParameters: '[RamlResourceQueryParameter!]',
         responses: '[RamlResourceResponse!]',
+        headers: '[RamlResourceHeaders!]',
         codeExamples: '[RamlResourceCodeExample!]',
       },
       interfaces: ['Method'],
@@ -113,6 +116,21 @@ const defineRamlResource = ({ schema, createTypes }) => {
       },
     }),
 
+    schema.buildObjectType({
+      name: 'RamlResourceHeaders',
+      fields: {
+        header: 'String!',
+        displayName: 'String',
+        default: 'String',
+        pattern: 'String',
+        type: 'String',
+        builtinType: 'String',
+        description: 'String',
+        required: 'Boolean',
+        enum: '[String!]',
+      },
+    }),
+
     schema.buildObjectType({
       name: 'RamlResourceMethodBody',
       fields: {