b/163142235 Update README with library and command line usage
Change-Id: I395fb47362d814345c510744154f3babb3431e1a
diff --git a/README.md b/README.md
index 58fc808..5dc745f 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,108 @@
command line application and a library of security tooling that analyzes the OAS
document.
+## Components
+- `oas-cli` : The command line tool with the main class to check security validation of specifications.
+- `oas-core` : The core library with features like parsing, traversing, and validating an OpenAPI Specification.
+- `oas-test` : This module contains any shared testing implementations like marker interfaces for integration tests.
+## Command Line Usage
+The command line tool can be invoked like:
+
+```java -jar api-security-tools.jar --file openApiSpecification.json ```
+
+It performs:
+- File validation.
+- OpenApi Specification Standard validation.
+- Supported security extensions validation.
+
+If there are any errors in the usage of the extensions, then the error type and message will be shown along with the extension path.
+
+## Building and Testing
+`./gradlew build`
+
+This will
+- Compile project.
+- Validate against ErrorProne and CheckStyle.
+- Run both unit and integration tests.
+- Generate code coverage report.
+
+## Validator Library
+
+The core library is responsible to traverse a YAML or JSON document and search for extensions. Every `Extension` can then be validated using custom validators.
+
+An example is shown below.
+
+Let's start by configuring the guice dependencies.
+```
+/**
+ * Guice module that installs all required bindings.
+ */
+public class MainModule extends AbstractModule {
+
+ @Override
+ protected void configure() {
+ install(new ExtendedValidatorMainModule());
+ install(new BaseParserModule());
+ binder().requireExplicitBindings();
+ }
+}
+```
+Create a simple validator that implements `ExtensionValidator`
+```
+class CustomValidator implements ExtensionValidator {
+
+ public CustomValidator() {}
+
+ @Override
+ public ImmutableSet<ExtensionValidationMessage> validate(Extension extension) {
+ // validation logic
+ // extension.getExtensionPath(), extension.getExtensionContent(), extension.getExtensionName()
+ }
+}
+```
+Inject the required dependencies into your class.
+```
+public class ExtensionValidationExample {
+
+ private BaseParser baseParser;
+ private ExtendedValidator extendedValidator;
+ private TraversalHelperFactory traversalHelperFactory;
+
+ @Inject
+ ExtensionValidationExample(BaseParser baseParser,
+ ExtendedValidator extendedValidator,
+ TraversalHelperFactory traversalHelperFactory) {
+ this.baseParser =baseParser;
+ this.extendedValidator = extendedValidator;
+ this.traversalHelperFactory = traversalHelperFactory;
+ }
+
+ void validate(File file) {
+ OpenApi3 openApi = baseParser.parse(file);
+
+ // Send traversal command for openapi object
+ TraversalHelper traversalHelper = traversalHelperFactory.create(ImmutableList.of());
+ traversalHelper.sendOpenApiTraversal(openApiSpec);
+ ImmutableSet<Extension> extensions = traversalHelper.traverse()
+
+ CustomValidator customValidator = new CustomValidator();
+
+ // Validate an extension
+ if(!extensions.isEmpty()) {
+ ImmutableSet<ExtensionValidationMessage> errors = extensions.iterator().next().validate(customValidator);
+ System.out.println("Found %d extension validation errors.\n\n", errors.size());
+ }
+ }
+}
+
+```
+Run it using:
+
+```
+ExtensionValidationExample extensionValidation = Guice.createInjector(new MainModule()).getInstance(ExtensionValidationExample.class);
+extensionValidation.validate(file);
+```
+
## LICENSE
Copyright 2020 Google LLC.
