generator-apiproxy

Scaffold an API proxy with quality gates for Swagger, (optional) Javascript callouts, and automated build, lint, test, API documentation, packaging, and deployment to your Apigee EDGE domain of choice.

generator-apiproxy creates a base template to start a new API Proxy with optional tools for custom Javascript callouts. It generates a repeatable, testable, and measurable workflow that lets you focus on innovation without sacrificing quality or extensibility.

Table of contents

• 1. Installation
• 2. Usage
  • 2.1. Generate a new API Proxy project
  • 2.2. Sub-generators
    • 2.2.1. apiproxy:boilerplate sub-generator
    • 2.2.2. apiproxy:editorconfig sub-generator
    • 2.2.3. apiproxy:eslint sub-generator
    • 2.2.4. apiproxy:git sub-generator
    • 2.2.5. apiproxy:jsc sub-generator
    • 2.2.6. apiproxy:nsp sub-generator
    • 2.2.7. apiproxy:readme sub-generator
• 3. Automating API Proxy CI/CD workflows
  • 3.1. Design your API with Swagger UI
  • 3.2. Build, lint, test, document, and push to Git
  • 3.3. Package all apiproxy artifacts
  • 3.4. Deploy the apiproxy package to Apigee EDGE
• 4. Quality gates, reports, and documentation
  • 4.1. Validate Swagger documentation
  • 4.2. Analyze Javascript callout source code
  • 4.3. Test Javascript callouts
  • 4.4. Generate API documentation and complexity reports
    • 4.4.1. Only generate OpenAPI/Swagger docs
    • 4.4.2. Only generate jsc API docs and complexity reports
• 5. Release management automation
• 6. Contributing to generator-apiproxy
• 7. Version and CHANGELOG
• 8. License

1. Installation

To install generator-apiproxy, open a terminal and run:

$ npm install generator-apiproxy --global

2. Usage

:information_source: generator-apiproxy will generate files in the current working directory, so be sure to change to a new directory first if you don't want to overwrite existing files.

generator-apiproxy supports CD workflows that can be executed in a command-line interface.

2.1. Generate a new API Proxy project

To scaffold a new API Proxy project, open a terminal and create a new, empty directory:

# Create a new directory
$ mkdir auth-proxy

# Enter your new directory
$ cd auth-proxy

Run the app generator:

# Scaffold a new API Proxy project
$ yo apigee-apiproxy
# Answer the prompts till done

2.2. Sub-generators

If you don't need all the features provided by the main generator, or you're working with an existing repository, you can still use a limited set of features by running these sub-generators directly.

:sos: Need help with a sub-generator?

You can view each sub-generator's options by running

# View usage help for a sub-generator
$ yo apiproxy:<sub-generator-name> --help

• apiproxy:boilerplate Generate common directories and files.
• apiproxy:editorconfig Generate an .editorconfig file.
• apiproxy:eslint Add ESLint with a standard configuration for code quality and vulnerability inspection.
• apiproxy:git Add .gitattributes and .gitignore files. (.gitignore provides common patterns for Javascript and Java projects.)
• apiproxy:jsc Stub a Javascript callout and its jest test.
• apiproxy:nsp Add the Node Security Program's nsp module to check for known Node.js vulnerabilities.
• apiproxy:readme Add are README.md to your repository's root.

2.2.1. apiproxy:boilerplate sub-generator

Generate common directories and files to facilitate team communication and standardize your CI/CD workflows:

$ yo apiproxy:boilerplate
# => create package.json
# => create jest.config.json
# => create sonar-project.properties
# => create .assets/README.md
# => create .assets/media/README.md
# => create .assets/media/audio/README.md
# => create .assets/media/img/README.md
# => create .assets/media/video/README.md
# => create .github/CODE_OF_CONDUCT.md
# => create .github/CONTRIBUTING.md
# => create .github/ISSUE_TEMPLATE.md
# => create .github/PULL_REQUEST_TEMPLATE.md
# => create .github/README.md
# => create apiproxy/README.md
# => create apiproxy/policies/README.md
# => create apiproxy/proxies/README.md
# => create apiproxy/resources/jsc/README.md
# => create apiproxy/targets/README.md
# => create openapi/README.md

# Install all dependencies and devDependencies
$ npm install

:bulb: Don't forget to run npm install!

2.2.2. apiproxy:editorconfig sub-generator

:speech_balloon: EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs. The EditorConfig project consists of a file format for defining coding styles and a collection of text editor plugins that enable editors to read the file format and adhere to defined styles. EditorConfig files are easily readable and they work nicely with version control systems.

Team, E. (n.d.). EditorConfig. Retrieved July 11, 2017, from http://editorconfig.org/

Add an .editorconfig file to your project's root directory:

# Run this from your project's root directory
$ yo apiproxy:editorconfig
# => create .editorconfig

2.2.3. apiproxy:eslint sub-generator

ESLint is a configurable linting utility that evaluates Javascript and JSX for code standards compliance and best practices. ESLint enjoys a wealth of plugins that also analyze source code for potential security vulnerabilities.

The apiproxy:eslint sub-generator

• Updates your project's package.json's devDependencies with:
  • eslint
  • eslint-config-xo-space
  • eslint-index
  • eslint-plugin-import
  • eslint-plugin-jest
  • eslint-plugin-jsdoc
  • eslint-plugin-no-unsafe-innerhtml
  • eslint-plugin-no-unsanitized
  • eslint-plugin-node
  • eslint-plugin-promise
  • eslint-plugin-scanjs-rules
  • eslint-plugin-security
  • eslint-plugin-standard
  • eslint-plugin-xss
• Adds an .eslintignore pre-configured to exclude third-party dependencies
• Adds an .eslintrc.yml file with strict-standard rules and plugins enabled.

Add ESLint to your project:

$ yo apiproxy:eslint
# =>  create .eslintignore
# => create .eslintrc.yml

# Install the new devDependencies
$ npm i

:bulb: Don't forget to run npm install!

2.2.4. apiproxy:git sub-generator

Avoid accidentally pushing unnecessary Node.js and Java files to your Git repository with a .gitignore file created on .gitignore.io.

Add .gitignore and .gitattributes files to your project:

$ yo apiproxy:git
# => create .gitattributes
# => create .gitignore

2.2.5. apiproxy:jsc sub-generator

Apigee lets you add custom JavaScript code that executes within the context of an API proxy flow. In your custom JavaScript code, you can use the objects, methods, and properties of the Apigee Edge JavaScript object model. The object model lets you get, set, and remove variables in the proxy flow context. You can also use basic cryptographic functions that are provided with the object model.

Create a Javascript callout (jsc) source code and jest test stubs:

# Add a Javascript callout and test stubs
$ yo apiproxy:jsc foo-bar-lib
# => create lib/foo-bar-lib.js
# => create lib/__tests__/fooBarLib.test.js

2.2.6. apiproxy:nsp sub-generator

The Node Security Platform provides continuous security monitoring for Node.js applications. These checks also integrate into your GitHub pull request flows.

Add Node Security Program checks to your project:

$ yo apiproxy:nsp
# => force package.json

# Install the nsp tools
$ npm install

:bulb: Don't forget to run npm install!

2.2.7. apiproxy:readme sub-generator

Your repository's "home page" is the README.md file. A good README helps attract new consumers as well as new contributors. Consequently, this sub-generator's README template includes a ScoreMe badge to grade your README's quality based on the same formula that CocaoPods uses to evaluate the quality of your copy.

Add a README (with badges) to your project:*

# Create a README.md (a repository home page)
$ yo apiproxy:readme
// => create README.md

# Create documentation
$ yo apiproxy:docs
// => create package.json
// => create docs/COMPLEXITY.md
// => create docs/JSCS.md
// => create docs/README.md
// => create docs/SWAGGER.md
// => create docs/TERMS_OF_SERVICE.md

# Add code quality and security analysis for Javascript callouts
$ yo apiproxy:eslint
// => create .eslintignore
// => create .eslintrc.yml

3. Automating API Proxy CI/CD workflows

Projects created with generator-apiproxy include npm-scripts that facilitate automated API Proxy design, builds, linting, testing, documentation, version control, semantic versioning, CHANGELOG generation, packaging, and deployment to Apigee EDGE.

Here's a recommended sequence of tasks and commands you can incorporate into your CI/CD value streams.

3.1. Design your API with Swagger UI

1. Go to the online Swagger Editor.
2. Create a well-formed Swagger document.
3. Copy the Swagger document to your clipboard.
4. Open an IDE and paste the Swagger's YAML into a new file.
5. Save the file to openapi directory.

3.2. Build, lint, test, document, and push to Git

If you're a lazy programmer (like me), you can run:

$ npm run build-test-push

Or, if that's too many characters for you, run the abbreviated command:

$ npm run btp

This will execute a:

1. :factory: Build. If the build passes, then it will execute
2. :100: Test, which includes these quality gates:
   1. :bathtub: Lint the
      • Swagger documents and the
      • Javascript callout source code (if any exists). If all's good, then it will
   2. :school: Test with jest. If all tests pass within the coverage threshold, it will check
   3. :lock: Security (with nsp). If prelimary security checks pass, it'll
3. :page_facing_up: Document your
   • Swagger spec and
   • Javascript callout code (both of which you'll find in the docs directory). Finally, it'll
4. :arrow_up: Commit and push to Git.

:warning: npm run btp generates an automated commit message

The prepend-header.sh shell script will use the default message "docs(api): auto-generate api docs and complexity report". The script can accept an alternate commit message, but that's not available from the npm-script btp, yet. If you want add that, submit a pull request :v:.

3.3. Package all apiproxy artifacts

Finally, you can update the repository's apiproxy -- your final build -- by running:

$ npm run apigee:apiproxy:update

This uses [openapi2apigee][openapi2apigee-url] behind the scenes to update the apiproxy artifacts and generate an apiproxy.zip file in your project's root directory.

3.4. Deploy the apiproxy package to Apigee EDGE

Run:

$ npm run apigee:apiproxy:deploy

This not only generates apiproxy artifacts, but also deploys to an Apigee EDGE host of your choosing.

4. Quality gates, reports, and documentation

generator-apiproxy creates a consistent repository with tools that enforce Swagger quality; Javascript quality; and Javascript unit tests and code coverage.

4.1. Validate Swagger documentation

:trophy: generator-apiproxy validates Swagger docs with swagger-cli.

swagger-cli validation runs before every test execution:

$ npm test

swagger-api/validator-badges display whether there are syntactic issues with you Swagger/OpenAPI 2.0 document:

• Valid: cordova-contacts.swagger.yaml
• Invalid:

4.2. Analyze Javascript callout source code

:closed_lock_with_key: :bath: :ocean: generator-apiproxy lints source code; checks for vulnerabilities; assesses dependency drift; and executes quality gates with BitHound, eslint, nsp, and SonarQube/sonarcloud.

The results are displayed real-time with README badges.

Code quality analysis runs before every test execution:

$ npm test

If you'd like an eslint report in HTML (with links to errors and warnings), run the following command to generate a eslint-report.html:

$ npm run eslint:html

4.3. Test Javascript callouts

:100: generator-apiproxy uses jest for BDD spec execution and code coverage analysis.

The results are displayed real-time with README badges.

Run:

$ npm test

This generates:

• Detailed code coverage reports at coverage/lcov-report/index.html, as well as
• lcov.info and clover.xml files, which you can send to CI test coverage services like Coveralls.
• Static markdown API documentation with complexity reports in the docs/ directory.

4.4. Generate API documentation and complexity reports

:page_facing_up: generator-apiproxy comes with jsdoc-to-markdown, complexity-report, and swagger-markdown that generate static markdown documentation.

To generate API docs, Swagger docs, and complexity reports in the docs directory, run:

$ npm run docs

4.4.1. Only generate OpenAPI/Swagger docs

If you want to inspect your static OpenAPI docs before you push to source control or before you release your apiproxy to Apigee EDGE, run:

# Only generate static Swagger API docs (as markdown)
$ npm run docs:swagger:apis

# Generate static Swagger API docs with custom parameters
$ npm run docs:swagger-markdown -- -i /path/to/swagger.yml -o /path/to/swagger-api.md

4.4.2. Only generate jsc API docs and complexity reports

If your apiproxy has Javascript callouts, you can preview your callouts' documentation and complexity reports in the docs directory by running:

$ npm run docs:jsc

# Access jsdoc2md directly, e.g.,
$ npm run docs:jsdoc2md --  --partial .assets/jsdoc2md/*.hbs --files lib/*.js > docs/README.md

5. Release management automation

If you and your team write commit messages that comply with the the Conventional Commit Message Specification, generator-apiproxy can use standard-version to automate

• Semantic versioning (with Git tags), and
• CHANGELOG generation

When you're ready to release, run:

$ npm run release

6. Contributing to generator-apiproxy

We welcome contributors and pull requests. Check out the guidelines for

• Contributing to generator-apiproxy and our
• Contributor Covenant Code of Conduct.

Contributions are stories with a beginning, a middle, and an end, all told through issues, comments, commit logs, and pull requests.

• Peruse open issues or
• Open a new pull request (PR)

Thanks goes to these wonderful people (emoji key):

| rm-cortez👀 | Spencer Hamm👀 | | :---: | :---: |

7. Version and CHANGELOG

generator-apiproxy's latest version is v1.0.0-beta.0. Please read the CHANGELOG for details.

8. License

Apache-2.0 © Greg Swindle