Skip to content

Commit

Permalink
update OpenAPI readme for CLI version v2.1 (#258)
Browse files Browse the repository at this point in the history
  • Loading branch information
@m-Bilal
m-Bilal authored Aug 22, 2024
1 parent 1764219 commit 82ae6a1
Showing 1 changed file with 51 additions and 90 deletions.
141 changes: 51 additions & 90 deletions registry/hasura/openapi/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,27 @@
# OpenAPI Lambda Connector

[![Docs](https://img.shields.io/badge/docs-v3.x-brightgreen.svg?style=flat)](https://hasura.io/docs/3.0/getting-started/overview/)
[![ndc-hub](https://img.shields.io/badge/ndc--hub-postgres-blue.svg?style=flat)](https://hasura.io/connectors)
[![License](https://img.shields.io/badge/license-Apache--2.0-purple.svg?style=flat)](LICENSE.txt)
[![Docs](https://img.shields.io/badge/docs-v3.x-brightgreen.svg?style=flat)](https://hasura.io/docs/3.0)
[![ndc-hub](https://img.shields.io/badge/ndc--hub-openapi-blue.svg?style=flat)](https://hasura.io/connectors/open-api-lambda)
[![License](https://img.shields.io/badge/license-Apache--2.0-purple.svg?style=flat)](https://www.apache.org/licenses/LICENSE-2.0)

The OpenAPI Lambda Connector allows you to import APIs that are documented in the OpenAPI/Swagger format into the Hasura Supergraph. The connector exposes REST API endpoints as Typescript functions, which can be exposed as GraphQL queries or mutations via the [NodeJS Lambda Connector](https://github.com/hasura/ndc-nodejs-lambda).

Functions that wrap GET requests are marked with a `@readonly` annotation, and are exposed as GraphQL Queries by the [NodeJS Lambda Connector](https://github.com/hasura/ndc-nodejs-lambda). All other request types are exposed as GraphQL Mutations.

This Connector implements the [Data Connector Spec](https://github.com/hasura/ndc-spec)

- [Hasura V3 Documentation](https://hasura.io/docs/3.0)
- [See the listing in the Hasura Hub](https://hasura.io/connectors/open-api-lambda)
- [Hasura DDN Documentation](https://hasura.io/docs/3.0)
- [Hasura DDN Quickstart](https://hasura.io/docs/3.0/getting-started/quickstart)
- [NodeJS Lambda Connector](https://github.com/hasura/ndc-nodejs-lambda)

Docs for the OpenAPI data connector:

- [Documentation](https://github.com/hasura/ndc-open-api-lambda/blob/main/docs/documentation.md)
- [Contributing](https://github.com/hasura/ndc-open-api-lambda/blob/main/docs/contributing.md)
- [Code of Conduct](https://github.com/hasura/ndc-open-api-lambda/blob/main/docs/code-of-conduct.md)
- [Relase Document](https://github.com/hasura/ndc-open-api-lambda/blob/main/docs/release.md)

## Features

- Convert Open API/swagger documentation into Typescript functions compatible with NodeJS Lambda Connector
Expand All @@ -29,120 +38,72 @@ This Connector implements the [Data Connector Spec](https://github.com/hasura/nd
## Before you get Started

1. Create a [Hasura Cloud account](https://console.hasura.io)
2. Install the [DDN CLI](https://hasura.io/docs/3.0/cli/installation/)
3. Please ensure that you have Docker installed and the Docker daemon is running.
4. If you want to make changes to the generated Typescript files, please ensure you have Node.js v20+ installed

## Quickstart using the DDN CLI

> [!TIP]
> The following instructions are intended to get you quickly started with using the OpenAPI Lambda connector.
> For further information on DDN, please check out the [Hasura DDN Getting Started Guide](https://hasura.io/docs/3.0/getting-started/overview/).
2. Please ensure you have the [DDN CLI](https://hasura.io/docs/3.0/cli/installation) and [Docker](https://docs.docker.com/engine/install/) installed
3. [Create a supergraph](https://hasura.io/docs/3.0/getting-started/init-supergraph)
4. [Create a subgraph](https://hasura.io/docs/3.0/getting-started/init-subgraph)
5. If you want to make changes to the generated Typescript files, please ensure you have Node.js v20+ installed

> [!NOTE]
> This section assumes that you have already setup a Supergraph and added a Subgraph.
## Using the OpenAPI connector

1. Initialize the connector
### Step 1: Authenticate your CLI session

```bash
ddn auth login
```
ddn connector init my_openapi --subgraph my_subgraph --hub-connector hasura/openapi
```

This will generate the necessary files into `my_subgraph/connector/my_openapi` directory. Supporting Typescript files for API calls will be created in this directory.

2. Add the correct environment variables to `/my_subgraph/connector/my_openapi/.env.local`. Supported environment variables and their description are listed under [Supported Environment Variables](#supported-environment-variables) section.

3. Modify the Docker container port in `my_subgraph/connector/my_openapi/docker-compose.my_openapi.yaml`. Typically, connectors default to port 8080. Each time you add a connector, please increment the published port by one to avoid port collisions. For example:
### Step 2: Configure the connector

```
ports:
- mode: ingress
target: 8080
published: '8082'
protocol: tcp
```
Once you have an initialized supergraph and subgraph, run the initialization command in interactive mode while
providing a name for the connector in the prompt:

4. Introspect the OpenAPI document using the connector

```
ddn connector introspect --connector my_subgraph/connector/my_openapi/connector.yaml
```bash
ddn connector init <connector-name> -i
```

This will introspect your OpenAPI document and create an `api.ts` file, a `functions.ts` file and other supporting files required to run the Typescript project.
#### Step 2.1: Choose `hasura/openapi` from the list

- The `api.ts` file contains the Data Types and API calls from the OpenAPI document
- The `functions.ts` file contains functions that wrap API calls. You can modify this `functions.ts` file to introduce business logic if you want to. See [Saving User Changes](#saving-user-changes) if you want to preserve your changes in this file when you introspect the OpenAPI document again.
#### Step 2.2: Choose a port for the connector

5. Add a [Data Connector Link](https://hasura.io/docs/3.0/supergraph-modeling/data-connector-links)

```
ddn connector-link add my_openapi --subgraph my_subgraph
```
The CLI will ask for a specific port to run the connector on. Choose a port that is not already in use or use the
default suggested port.

This will create a file `my_subgraph/metadata/my_openapi.hml` that links your OpenAPI Connector to your Hasura Supergraph.
#### Step 2.3: Provide the env vars required for the connector

6. Update the evironment variables listed in `my_subgraph/metadata/my_openapi.hml` (here, `MY_SUBGRAPH_MY_OPENAPI_READ_URL` and `MY_SUBGRAPH_MY_OPENAPI_WRITE_URL`) in `my_subgraph/.env.my_subgraph`.
Environment variables that can be used to configure the connector are listed under [Supported Environment Variables](https://github.com/hasura/ndc-open-api-lambda/blob/main/docs/documentation.md#supported-environment-variables).

7. Add the connector's Docker Compose file to your project's Docker Compose file (your project's Docker Compose file is the one that's located in the root directory your project):
## Step 3: Introspect the connector

```bash
ddn connector introspect <connector-name>
```
include:
- path: my_subpgraph/connector/my_openapi/docker-compose.my_openapi.yaml
```

Start the GraphQL engine, observability tools, and the connector:

```
HASURA_DDN_PAT=$(ddn auth print-pat) docker compose -f docker-compose.hasura.yaml watch
```
This will generate the required metadata and TypeScript files.

The `http://localhost:${your-docker-container-port}/schema/` should return the schema of your OpenAPI Connector. All functions that wrap `GET` requests will be listed in the `functions` array, while all other functions will be listed in the `procedures` array.
## Step 4: Add your resources

8. Add the connector schema to [Data Connector Link](<(https://hasura.io/docs/3.0/supergraph-modeling/data-connector-links)>)

```
ddn connector-link update my_openapi --subgraph my_subgraph
```bash
ddn connector-link add-resources <connector-name>
```

This command will modify `my_subgraph/metadata/my_openapi.hml`, and the schema of the connector will be added to the `definition.schema` key.
This command will track all the API endpoints in your OpenAPI Document as [Commands](https://hasura.io/docs/3.0/supergraph-modeling/commands/).

9. Add all resources in your connector schema to your GraphQL API
## Saving User Changes

```
ddn connector-link update my_openapi --subgraph my_subgraph --add-all-resources
```

This will create HML files that represent resources in your connector schema at `my_subgraph/metadata`. These HML files specify your GraphQL API.

You have now added the OpenAPI Connector and imported all of your APIs in your supergraph. You can now:
Please refer to [Saving User Changes](https://github.com/hasura/ndc-open-api-lambda/blob/main/docs/documentation.md#saving-user-changes).

- Deploy the supergraph to Hasura DDN (Please follow the steps [here](https://hasura.io/docs/3.0/getting-started/deployment/))
- Run the supergraph locally for debugging (Please follow the steps [here](https://hasura.io/docs/3.0/getting-started/build-your-api))
## Known Limiations

## Documentation
- Support for [Relaxed Types](https://github.com/hasura/ndc-nodejs-lambda/tree/main?tab=readme-ov-file#relaxed-types) is a WiP.
- [Types not supported by the NodeJS Lambda Connector](https://github.com/hasura/ndc-nodejs-lambda?tab=readme-ov-file#unsupported-types) are not supported.

This connector is published as a Docker Image. The image name is `ghcr.io/hasura/ndc-open-api-lambda`. The Docker Image accepts the following environment variables that can be used to alter its functionality.
## Contributing

### Supported Environment Variables
Check out our [contributing guide](.docs/contributing.md) for more details.

1. `NDC_OAS_DOCUMENT_URI` (optional): The URI to your Open API Document. If you're using a file instead of a HTTP link, please ensure that it is named `swagger.json` and is present in the root directory of the volume being mounted to `/etc/connector` (for this tutorial, the `swagger.json` file should be present at `my_subgraph/connector/my_openapi/`).
2. `NDC_OAS_BASE_URL` (optional): The base URL of your API.
3. `NDC_OAS_FILE_OVERWRITE` (optional): A Boolean flag to allow previously generated files to be over-written. Defaults to `false`.
4. `HASURA_PLUGIN_LOG_LEVEL` (optional): The log level. Possible values: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`. Defaults to `info`
5. `NDC_OAS_LAMBDA_PRETTY_LOGS` (optional): A Boolean flag to print human readable logs instead of JSON. Defaults to `false`
## Changelog

### Saving User Changes
Please refer to the [changelog](https://github.com/hasura/ndc-open-api-lambda/blob/main/changelog.md).

When re-introspecting the connector, user changes in `functions.ts` can be preserved by adding an `@save` JS Doc Tag to the documentation comment of a function. This will ensure that that function is not overwritten and the saved function will be added if missing in the newly generated `functions.ts`
## License

Example

```
/**
* Dummy function that mutates an API response
* @save
*/
function mutateResponse(response: ApiResponseObject) {
response.description = "This API does some work. I hope that's helpful";
}
```
The Open API Lambda Connector is available under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).

0 comments on commit 82ae6a1

Please sign in to comment.