mw-apigee-apiproxy v1.0.0-alpha.0

mw-apigee-apiproxy

1. Installation

To install mw-apigee-apiproxy, run:

$ npm install mw-apigee-apiproxy --global

2. Usage

mw-apigee-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.

mw-apigee-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 foo-proxy

# Enter your new directory
$ cd foo-proxy

Run the app generator:

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

3. Automating API Proxy CI/CD workflows

Projects created with mw-apigee-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:

3. :bathtub: Lint the

   • Swagger documents and the
   • Javascript callout source code (if any exists). If all's good, then it will

4. :school: Test with jest. If all tests pass within the coverage threshold, it will check

5. :lock: Security (with nsp). If prelimary security checks pass, it'll

6. :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 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

mw-apigee-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: mw-apigee-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: mw-apigee-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: mw-apigee-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: mw-apigee-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, mw-apigee-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