Skip to content

[Spec-Insert] Added Readme file for Spec-Insert #9638

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Apr 18, 2025
Merged

[Spec-Insert] Added Readme file for Spec-Insert #9638

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cde3e7e
Added Readme file for Spec-Insert
nhtruong Apr 16, 2025
634b4de
Update README.md
Naarcha-AWS Apr 17, 2025
7fdec01
Merge branch 'main' into spec-insert/docs
Naarcha-AWS Apr 17, 2025
baed1ac
Apply suggestions from code review
Naarcha-AWS Apr 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions spec-insert/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Spec-insert plugin overview

This plugin facilitates the insertion of OpenAPI spec components into Markdown files. It provides a set of snippets that you can use to insert various components, such as API paths, path parameters, and query parameters. This document provides an overview of the plugin's codebase. The codebase is divided into the following sections:

- API parser: Parses the OpenAPI spec and extracts the relevant component information
- Component renderer: Renders the extracted component information into Markdown format
- Reports: Generates reports for this plugin

## API parser

The following section provides information about the components of the API parser.

### SpecHash

The [`SpecHash`](./lib/spec_hash.rb) class is responsible for ingesting the OpenAPI spec and dereferencing the `$ref` fields. Its `.load_file` method accepts the path to the OpenAPI spec file and sets up all API actions found in the spec. This is also where the `text_replacements` feature from the config file is managed.

Check failure on line 15 in spec-insert/README.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: dereferencing. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: dereferencing. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "spec-insert/README.md", "range": {"start": {"line": 15, "column": 94}}}, "severity": "ERROR"}

### API::Operation

Check failure on line 17 in spec-insert/README.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.HeadingCapitalization] 'API::Operation' is a heading and should be in sentence case.

Raw Output:
{"message": "[OpenSearch.HeadingCapitalization] 'API::Operation' is a heading and should be in sentence case.", "location": {"path": "spec-insert/README.md", "range": {"start": {"line": 17, "column": 5}}}, "severity": "ERROR"}

The [`API::Operation`](./lib/api/operation.rb) class represents an OpenAPI operation. Operations of the same group constitute an API.

### API::Action

Check failure on line 21 in spec-insert/README.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.HeadingCapitalization] 'API::Action' is a heading and should be in sentence case.

Raw Output:
{"message": "[OpenSearch.HeadingCapitalization] 'API::Action' is a heading and should be in sentence case.", "location": {"path": "spec-insert/README.md", "range": {"start": {"line": 21, "column": 5}}}, "severity": "ERROR"}

The [`API::Action`](./lib/api/action.rb) class represents an API action, which comprises the URL path, query parameters, path parameters, request body, and response body. The components are represented by the following classes:

- [`API::Parameter`](./lib/api/parameter.rb)
- [`API::Body`](./lib/api/body.rb)

## Component renderer

Components are rendered into Markdown using `mustache` [templates](./lib/renderers/templates). Each spec-insert component is represented by a renderer class:

- [`BodyParameter`](./lib/renderers/body_parameters.rb): Renders the request and response body tables
- [`PathParameter`](./lib/renderers/path_parameters.rb): Renders the path parameters table
- [`QueryParameter`](./lib/renderers/query_parameters.rb): Renders the query parameters table
- [`Endpoint`](./lib/renderers/endpoints.rb): Renders a list of endpoints

Each of these components is rendered within a [`SpecInsert`](./lib/renderers/spec_insert.rb) class, which wraps the rendered component within `<!-- spec_insert_start -->` and `<!-- spec_insert_end -->` comments.

## Reports

The [reports](./lib/reports) folder contains code that generates utilization and dry-run reports. You can trigger these reports through the [`Rakefile`](Rakefile).
Loading