1996

pending completion

Build # 1996

Build Type

Pull #1311

travis-ci-com

Committed by

web-flow

Commit Message

<a href="https://github.com/Redocly/redoc/commit/<a class=hub.com/Redocly/redoc/commit/<a class="double-link" href="https://git"><a class=hub.com/Redocly/redoc/commit/<a class="double-link" href="https://git"><a class=hub.com/Redocly/redoc/commit/<a class="double-link" href="https://git"><a class=hub.com/Redocly/redoc/commit/<a class="double-link" href="https://git"><a class=hub.com/Redocly/redoc/commit/0d3e463780be90ed900dee06e9f74b213dd31940">0d3e46378">&lt;a href=&quot;https://github.com/Redocly/redoc/commit/</a><a class="double-link" href="https://github.com/Redocly/redoc/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/Redocly/redoc/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/Redocly/redoc/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/Redocly/redoc/commit/0d3e463780be90ed900dee06e9f74b213dd31940">0d3e46378</a><a href="https://github.com/Redocly/redoc/commit/0d3e463780be90ed900dee06e9f74b213dd31940">&lt;a href=&quot;https://github.com/Redocly/redoc/commit/0d3e463780be90ed900dee06e9f74b213dd31940&quot;&gt;&amp;quot;&amp;gt;&amp;amp;lt;a href=&amp;amp;quot;https://github.com/Redocly/redoc/commit/&amp;lt;/a&amp;gt;&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://github.com/Redocly/redoc/commit/&amp;amp;lt;a class=&amp;amp;quot;double-link&amp;amp;quot; href=&amp;amp;quot;https://git&amp;quot;&amp;gt;&amp;amp;lt;a class=&amp;lt;/a&amp;gt;hub.com/Redocly/redoc/commit/0d3e463780be90ed900dee06e9f74b213dd31940&amp;quot;&amp;gt;0d3e46378&amp;lt;/a&amp;gt;&amp;lt;a href=&amp;quot;https://github.com/Redocly/redoc/commit/0d3e463780be90ed900dee06e9f74b213dd31940&amp;quot;&amp;gt;&amp;amp;lt;a href=&amp;amp;quot;https://github.com/Redocly/redoc/commit/0d3e463780be90ed900dee06e9f74b21&amp;lt;/a&amp;gt;3</a>dd31940&quot;&gt;&amp;quot;&amp;gt;Merge &amp;lt;/a&amp;gt;&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://github.com/Redocly/redoc/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://github.com/Redocly/redoc/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://github.com/Redocly/redoc/commit/45a087c9c&quot;&gt;45a087c9c&lt;/a&gt;&lt;a href=&quot;https://github.com/Redocly/redoc/co... (continued)

Pull Request Pull Request #1311: feat: move description sections to the end with 'sectionsAtTheEnd' op…

Run Details

1614 of 2375 branches covered (67.96%)

Branch coverage included in aggregate %.

14 of 14 new or added lines in 3 files covered. (100.0%)

3251 of 4035 relevant lines covered (80.57%)

128.46 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

75.5

/src/services/MenuBuilder.ts

import {
  OpenAPIOperation,
  OpenAPIParameter,
  OpenAPISpec,
  OpenAPITag,
  Referenced,
  OpenAPIServer,
  OpenAPIPaths,
} from '../types';
import {
  isOperationName,
  SECURITY_DEFINITIONS_COMPONENT_NAME,
  setSecuritySchemePrefix,
  JsonPointer,
} from '../utils';
import { MarkdownRenderer } from './MarkdownRenderer';
import { GroupModel, OperationModel } from './models';
import { OpenAPIParser } from './OpenAPIParser';
import { RedocNormalizedOptions } from './RedocNormalizedOptions';

export type TagInfo = OpenAPITag & {
  operations: ExtendedOpenAPIOperation[];
  used?: boolean;
};

export type ExtendedOpenAPIOperation = {
  pointer: string;
  pathName: string;
  httpVerb: string;
  pathParameters: Array<Referenced<OpenAPIParameter>>;
  pathServers: Array<OpenAPIServer> | undefined;
  isWebhook: boolean;
} & OpenAPIOperation;

export type TagsInfoMap = Record<string, TagInfo>;

export interface TagGroup {
  name: string;
  tags: string[];
}

export const GROUP_DEPTH = 0;
export type ContentItemModel = GroupModel | OperationModel;

export class MenuBuilder {
  /**
   * Builds page content structure based on tags
   */
  static buildStructure(
    parser: OpenAPIParser,
    options: RedocNormalizedOptions,
  ): ContentItemModel[] {
    const spec = parser.spec;

    const items: ContentItemModel[] = [];
    const tagsMap = MenuBuilder.getTagsWithOperations(spec);

    const mdHeadings = MenuBuilder.addMarkdownItems(
      spec.info.description || '',
      undefined,
      1,
      options,
    );
    const mdHeadingsBefore = mdHeadings.filter(h => !options.sectionsAtTheEnd.includes(h.name));
    const mdHeadingsAfter = mdHeadings.filter(h => options.sectionsAtTheEnd.includes(h.name));

    items.push(...mdHeadingsBefore);
    if (spec['x-tagGroups'] && spec['x-tagGroups'].length > 0) {
      items.push(
        ...MenuBuilder.getTagGroupsItems(parser, undefined, spec['x-tagGroups'], tagsMap, options),
      );

      if (mdHeadingsAfter.length > 0) {
        mdHeadingsAfter[0].topMargin = true;
      }
    } else {
      items.push(...MenuBuilder.getTagsItems(parser, tagsMap, undefined, undefined, options));
    }

    items.push(...mdHeadingsAfter);

    return items;
  }

  /**
   * extracts items from markdown description
   * @param description - markdown source
   */
  static addMarkdownItems(
    description: string,
    parent: GroupModel | undefined,
    initialDepth: number,
    options: RedocNormalizedOptions,
  ): ContentItemModel[] {
    const renderer = new MarkdownRenderer(options);
    const headings = renderer.extractHeadings(description || '');

    if (headings.length && parent && parent.description) {
      parent.description = MarkdownRenderer.getTextBeforeHading(
        parent.description,
        headings[0].name,
      );
    }

    const mapHeadingsDeep = (_parent, items, depth = 1) =>
      items.map(heading => {
        const group = new GroupModel('section', heading, _parent);
        group.depth = depth;
        if (heading.items) {
          group.items = mapHeadingsDeep(group, heading.items, depth + 1);
        }
        if (
          MarkdownRenderer.containsComponent(
            group.description || '',
            SECURITY_DEFINITIONS_COMPONENT_NAME,
          )
        ) {
          setSecuritySchemePrefix(group.id + '/');
        }
        return group;
      });

    return mapHeadingsDeep(parent, headings, initialDepth);
  }

  /**
   * Returns array of OperationsGroup items for the tag groups (x-tagGroups vendor extension)
   * @param tags value of `x-tagGroups` vendor extension
   */
  static getTagGroupsItems(
    parser: OpenAPIParser,
    parent: GroupModel | undefined,
    groups: TagGroup[],
    tags: TagsInfoMap,
    options: RedocNormalizedOptions,
  ): GroupModel[] {
    const res: GroupModel[] = [];
    for (const group of groups) {
      const item = new GroupModel('group', group, parent);
      item.depth = GROUP_DEPTH;
      item.items = MenuBuilder.getTagsItems(parser, tags, item, group, options);
      res.push(item);
    }
    // TODO checkAllTagsUsedInGroups
    return res;
  }

  /**
   * Returns array of OperationsGroup items for the tags of the group or for all tags
   * @param tagsMap tags info returned from `getTagsWithOperations`
   * @param parent parent item
   * @param group group which this tag belongs to. if not provided gets all tags
   */
  static getTagsItems(
    parser: OpenAPIParser,
    tagsMap: TagsInfoMap,
    parent: GroupModel | undefined,
    group: TagGroup | undefined,
    options: RedocNormalizedOptions,
  ): ContentItemModel[] {
    let tagNames;

    if (group === undefined) {
      tagNames = Object.keys(tagsMap); // all tags
    } else {
      tagNames = group.tags;
    }

    const tags = tagNames.map(tagName => {
      if (!tagsMap[tagName]) {
        console.warn(`Non-existing tag "${tagName}" is added to the group "${group!.name}"`);
        return null;
      }
      tagsMap[tagName].used = true;
      return tagsMap[tagName];
    });

    const res: Array<GroupModel | OperationModel> = [];
    for (const tag of tags) {
      if (!tag) {
        continue;
      }
      const item = new GroupModel('tag', tag, parent);
      item.depth = GROUP_DEPTH + 1;

      // don't put empty tag into content, instead put its operations
      if (tag.name === '') {
        const items = [
          ...MenuBuilder.addMarkdownItems(tag.description || '', item, item.depth + 1, options),
          ...this.getOperationsItems(parser, undefined, tag, item.depth + 1, options),
        ];
        res.push(...items);
        continue;
      }

      item.items = [
        ...MenuBuilder.addMarkdownItems(tag.description || '', item, item.depth + 1, options),
        ...this.getOperationsItems(parser, item, tag, item.depth + 1, options),
      ];

      res.push(item);
    }
    return res;
  }

  /**
   * Returns array of Operation items for the tag
   * @param parent parent OperationsGroup
   * @param tag tag info returned from `getTagsWithOperations`
   * @param depth items depth
   */
  static getOperationsItems(
    parser: OpenAPIParser,
    parent: GroupModel | undefined,
    tag: TagInfo,
    depth: number,
    options: RedocNormalizedOptions,
  ): OperationModel[] {
    if (tag.operations.length === 0) {
      return [];
    }

    const res: OperationModel[] = [];
    for (const operationInfo of tag.operations) {
      const operation = new OperationModel(parser, operationInfo, parent, options);
      operation.depth = depth;
      res.push(operation);
    }
    return res;
  }

  /**
   * collects tags and maps each tag to list of operations belonging to this tag
   */
  static getTagsWithOperations(spec: OpenAPISpec): TagsInfoMap {
    const tags: TagsInfoMap = {};
    for (const tag of spec.tags || []) {
      tags[tag.name] = { ...tag, operations: [] };
    }

    getTags(spec.paths);
    if (spec['x-webhooks']) {
      getTags(spec['x-webhooks'], true);
    }

    function getTags(paths: OpenAPIPaths, isWebhook?: boolean) {
      for (const pathName of Object.keys(paths)) {
        const path = paths[pathName];
        const operations = Object.keys(path).filter(isOperationName);
        for (const operationName of operations) {
          const operationInfo = path[operationName];
          let operationTags = operationInfo.tags;

          if (!operationTags || !operationTags.length) {
            // empty tag
            operationTags = [''];
          }

          for (const tagName of operationTags) {
            let tag = tags[tagName];
            if (tag === undefined) {
              tag = {
                name: tagName,
                operations: [],
              };
              tags[tagName] = tag;
            }
            if (tag['x-traitTag']) {
              continue;
            }
            tag.operations.push({
              ...operationInfo,
              pathName,
              pointer: JsonPointer.compile(['paths', pathName, operationName]),
              httpVerb: operationName,
              pathParameters: path.parameters || [],
              pathServers: path.servers,
              isWebhook: !!isWebhook,
            });
          }
        }
      }
    }
    return tags;
  }
}

1	import {
2	OpenAPIOperation,
3	OpenAPIParameter,
4	OpenAPISpec,
5	OpenAPITag,
6	Referenced,
7	OpenAPIServer,
8	OpenAPIPaths,
9	} from '../types';
10	import {	7✔
11	isOperationName,
12	SECURITY_DEFINITIONS_COMPONENT_NAME,
13	setSecuritySchemePrefix,
14	JsonPointer,
15	} from '../utils';
16	import { MarkdownRenderer } from './MarkdownRenderer';	7✔
17	import { GroupModel, OperationModel } from './models';	7✔
18	import { OpenAPIParser } from './OpenAPIParser';
19	import { RedocNormalizedOptions } from './RedocNormalizedOptions';
20
21	export type TagInfo = OpenAPITag & {
22	operations: ExtendedOpenAPIOperation[];
23	used?: boolean;
24	};
25
26	export type ExtendedOpenAPIOperation = {
27	pointer: string;
28	pathName: string;
29	httpVerb: string;
30	pathParameters: Array<Referenced<OpenAPIParameter>>;
31	pathServers: Array<OpenAPIServer> \| undefined;
32	isWebhook: boolean;
33	} & OpenAPIOperation;
34
35	export type TagsInfoMap = Record<string, TagInfo>;
36
37	export interface TagGroup {
38	name: string;
39	tags: string[];
40	}
41
42	export const GROUP_DEPTH = 0;	7✔
43	export type ContentItemModel = GroupModel \| OperationModel;
44
45	export class MenuBuilder {	7✔
46	/**
47	* Builds page content structure based on tags
48	*/
49	static buildStructure(	7✔
50	parser: OpenAPIParser,
51	options: RedocNormalizedOptions,
52	): ContentItemModel[] {
53	const spec = parser.spec;	2✔
54
55	const items: ContentItemModel[] = [];	2✔
56	const tagsMap = MenuBuilder.getTagsWithOperations(spec);	2✔
57
58	const mdHeadings = MenuBuilder.addMarkdownItems(	2✔
59	spec.info.description \|\| '',	2!
60	undefined,
61	1,
62	options,
63	);
64	const mdHeadingsBefore = mdHeadings.filter(h => !options.sectionsAtTheEnd.includes(h.name));	8✔
65	const mdHeadingsAfter = mdHeadings.filter(h => options.sectionsAtTheEnd.includes(h.name));	8✔
66
67	items.push(...mdHeadingsBefore);	2✔
68	if (spec['x-tagGroups'] && spec['x-tagGroups'].length > 0) {	2!
69	items.push(	2✔
70	...MenuBuilder.getTagGroupsItems(parser, undefined, spec['x-tagGroups'], tagsMap, options),
71	);
72
73	if (mdHeadingsAfter.length > 0) {	2!
74	mdHeadingsAfter[0].topMargin = true;	×
75	}
76	} else {
77	items.push(...MenuBuilder.getTagsItems(parser, tagsMap, undefined, undefined, options));	×
78	}
79
80	items.push(...mdHeadingsAfter);	2✔
81
82	return items;	2✔
83	}
84
85	/**
86	* extracts items from markdown description
87	* @param description - markdown source
88	*/
89	static addMarkdownItems(	7✔
90	description: string,
91	parent: GroupModel \| undefined,
92	initialDepth: number,
93	options: RedocNormalizedOptions,
94	): ContentItemModel[] {
95	const renderer = new MarkdownRenderer(options);	12✔
96	const headings = renderer.extractHeadings(description \|\| '');	12!
97
98	if (headings.length && parent && parent.description) {	12!
99	parent.description = MarkdownRenderer.getTextBeforeHading(	×
100	parent.description,
101	headings[0].name,
102	);
103	}
104
105	const mapHeadingsDeep = (_parent, items, depth = 1) =>	20!
106	items.map(heading => {	20✔
107	const group = new GroupModel('section', heading, _parent);	8✔
108	group.depth = depth;	8✔
109	if (heading.items) {	8!
110	group.items = mapHeadingsDeep(group, heading.items, depth + 1);	8✔
111	}
112	if (	8!
113	MarkdownRenderer.containsComponent(
114	group.description \|\| '',	8!
115	SECURITY_DEFINITIONS_COMPONENT_NAME,
116	)
117	) {
118	setSecuritySchemePrefix(group.id + '/');	×
119	}
120	return group;	8✔
121	});
122
123	return mapHeadingsDeep(parent, headings, initialDepth);	12✔
124	}
125
126	/**
127	* Returns array of OperationsGroup items for the tag groups (x-tagGroups vendor extension)
128	* @param tags value of `x-tagGroups` vendor extension
129	*/
130	static getTagGroupsItems(	7✔
131	parser: OpenAPIParser,
132	parent: GroupModel \| undefined,
133	groups: TagGroup[],
134	tags: TagsInfoMap,
135	options: RedocNormalizedOptions,
136	): GroupModel[] {
137	const res: GroupModel[] = [];	2✔
138	for (const group of groups) {	6✔
139	const item = new GroupModel('group', group, parent);	6✔
140	item.depth = GROUP_DEPTH;	6✔
141	item.items = MenuBuilder.getTagsItems(parser, tags, item, group, options);	6✔
142	res.push(item);	6✔
143	}
144	// TODO checkAllTagsUsedInGroups
145	return res;	2✔
146	}
147
148	/**
149	* Returns array of OperationsGroup items for the tags of the group or for all tags
150	* @param tagsMap tags info returned from `getTagsWithOperations`
151	* @param parent parent item
152	* @param group group which this tag belongs to. if not provided gets all tags
153	*/
154	static getTagsItems(	7✔
155	parser: OpenAPIParser,
156	tagsMap: TagsInfoMap,
157	parent: GroupModel \| undefined,
158	group: TagGroup \| undefined,
159	options: RedocNormalizedOptions,
160	): ContentItemModel[] {
161	let tagNames;
162
163	if (group === undefined) {	6!
164	tagNames = Object.keys(tagsMap); // all tags	×
165	} else {
166	tagNames = group.tags;	6✔
167	}
168
169	const tags = tagNames.map(tagName => {	6✔
170	if (!tagsMap[tagName]) {	10!
171	console.warn(`Non-existing tag "${tagName}" is added to the group "${group!.name}"`);	×
172	return null;	×
173	}
174	tagsMap[tagName].used = true;	10✔
175	return tagsMap[tagName];	10✔
176	});
177
178	const res: Array<GroupModel \| OperationModel> = [];	6✔
179	for (const tag of tags) {	12✔
180	if (!tag) {	10!
181	continue;	×
182	}
183	const item = new GroupModel('tag', tag, parent);	10✔
184	item.depth = GROUP_DEPTH + 1;	10✔
185
186	// don't put empty tag into content, instead put its operations
187	if (tag.name === '') {	10!
188	const items = [	×
189	...MenuBuilder.addMarkdownItems(tag.description \|\| '', item, item.depth + 1, options),	×
190	...this.getOperationsItems(parser, undefined, tag, item.depth + 1, options),
191	];
192	res.push(...items);	×
193	continue;	×
194	}
195
196	item.items = [	10✔
197	...MenuBuilder.addMarkdownItems(tag.description \|\| '', item, item.depth + 1, options),	10!
198	...this.getOperationsItems(parser, item, tag, item.depth + 1, options),
199	];
200
201	res.push(item);	10✔
202	}
203	return res;	6✔
204	}
205
206	/**
207	* Returns array of Operation items for the tag
208	* @param parent parent OperationsGroup
209	* @param tag tag info returned from `getTagsWithOperations`
210	* @param depth items depth
211	*/
212	static getOperationsItems(	7✔
213	parser: OpenAPIParser,
214	parent: GroupModel \| undefined,
215	tag: TagInfo,
216	depth: number,
217	options: RedocNormalizedOptions,
218	): OperationModel[] {
219	if (tag.operations.length === 0) {	10✔
220	return [];	4✔
221	}
222
223	const res: OperationModel[] = [];	6✔
224	for (const operationInfo of tag.operations) {	44✔
225	const operation = new OperationModel(parser, operationInfo, parent, options);	44✔
226	operation.depth = depth;	44✔
227	res.push(operation);	44✔
228	}
229	return res;	6✔
230	}
231
232	/**
233	* collects tags and maps each tag to list of operations belonging to this tag
234	*/
235	static getTagsWithOperations(spec: OpenAPISpec): TagsInfoMap {	7✔
236	const tags: TagsInfoMap = {};	2✔
237	for (const tag of spec.tags \|\| []) {	10!
238	tags[tag.name] = { ...tag, operations: [] };	10✔
239	}
240
241	getTags(spec.paths);	2✔
242	if (spec['x-webhooks']) {	2!
243	getTags(spec['x-webhooks'], true);	2✔
244	}
245
246	function getTags(paths: OpenAPIPaths, isWebhook?: boolean) {
247	for (const pathName of Object.keys(paths)) {	32✔
248	const path = paths[pathName];	32✔
249	const operations = Object.keys(path).filter(isOperationName);	32✔
250	for (const operationName of operations) {	64✔
251	const operationInfo = path[operationName];	44✔
252	let operationTags = operationInfo.tags;	44✔
253
254	if (!operationTags \|\| !operationTags.length) {	44!
255	// empty tag
256	operationTags = [''];	×
257	}
258
259	for (const tagName of operationTags) {	88✔
260	let tag = tags[tagName];	44✔
261	if (tag === undefined) {	44!
262	tag = {	×
263	name: tagName,
264	operations: [],
265	};
266	tags[tagName] = tag;	×
267	}
268	if (tag['x-traitTag']) {	44!
269	continue;	×
270	}
271	tag.operations.push({	44✔
272	...operationInfo,
273	pathName,
274	pointer: JsonPointer.compile(['paths', pathName, operationName]),
275	httpVerb: operationName,
276	pathParameters: path.parameters \|\| [],	84✔
277	pathServers: path.servers,
278	isWebhook: !!isWebhook,
279	});
280	}
281	}
282	}
283	}
284	return tags;	2✔
285	}
286	}	7✔

Redocly / redoc / 1996

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous