Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/scottlogic/openapi-forge-javascript

⚒️ OpenAPI Forge generator for JavaScript clients
https://github.com/scottlogic/openapi-forge-javascript

Last synced: about 7 hours ago
JSON representation

⚒️ OpenAPI Forge generator for JavaScript clients

Awesome Lists containing this project

README 

        
# OpenAPI Forge - JavaScript



This repository is the JavaScript generator for the [OpenAPI Forge](https://github.com/ScottLogic/openapi-forge), see that repository for usage instructions:



https://github.com/ScottLogic/openapi-forge



The client API it generates is suitable for running in the browser (after being bundled appropriately), or via node. The generated code uses the Fetch API, and as a result you'll need to use node v18 or greater.



- [OpenAPI Forge - JavaScript](#openapi-forge---javascript)

  - [Example](#example)

    - [Running with node (\>= v18)](#running-with-node--v18)

    - [Running in the browser](#running-in-the-browser)

  - [Configuration](#configuration)

  - [Development](#development)

    - [Running](#running)

    - [Testing](#testing)

    - [Linting](#linting)



## Example



You should consult the [OpenAPI Forge](https://github.com/ScottLogic/openapi-forge) repository for a complete user guide. The following is a very brief example that quikcly gets you up-and-running with this generator.



Run the `forge` command to generate a client API using this generator as follows:



```

$ openapi-forge forge \

                https://petstore3.swagger.io/api/v3/openapi.json \

                openapi-forge-javascript \

                -o api

```



This will generate various files in the `api` folder.



### Running with node (>= v18)



Add the following `index.js` in the `api` folder:



```javascript

const ApiPet = require("./apiPet");

const Configuration = require("./configuration");

const transport = require("./fetch");



// create an API client

const config = new Configuration(transport);

config.basePath = "https://petstore3.swagger.io";

const api = new ApiPet(config);



// use it!

(async () => {

  await api.addPet({

    id: 1,

    name: "Fido",

    photoUrls: [],

  });



  const pet = await api.getPetById(1);

  console.log(pet.name);

})();

```



To test the API, this example adds a Pet named “Fido” to the Pet Store, then retrieves it via its id, logging the name. You can run the example as follows:



```

% node index.js

Fido

```



### Running in the browser



You'll need to bundle the files into a single script, there are various tools that can be used for this purpose, but browserify is one of the simplest:



```

% npx browserify index.js -o bundle.js

```



Next create a simple HTML file that loads this script:



```



```



Load the above page in a browser and you should see `Fido` logged to the console.



## Configuration



OpenAPI Forge is opinionated in its approach, we don't provide a vast range of configuration options, just the essentials! You can list the generator-specific configuration options by running the `generate-options` command as follows:



```

% openapi-forge generator-options openapi-forge-javascript

This generator has a number of additional options which can be supplied when executing the 'forge' command.



Options:

  --generator.moduleFormat   The module format to use for the generated code. (choices: "commonjs", "esmodule",

                                    default: "commonjs")

```



## Development



The OpenAPI Forge project [details the process for creating a new generator](https://github.com/ScottLogic/openapi-forge#generator-development). The documentation gives a few generator-specific instructions.



### Running



To run this generator, you also need to have [OpenAPI Forge] installed, or the repository checked out. Assuming you have it installed as a global module, you can run this generator as follows:



```

$ openapi-forge forge \

                https://petstore3.swagger.io/api/v3/openapi.json \

                . \

                -o api \

```



This generates an API from the Pet Store swagger definition, using the generator within the current folder (`.`), outputting the results to the `api` folder.



### Testing



The standard test script is used to execute the BDD-style tests against this generator.



```

npm run test

```



The script expects that the openapi-forge project (which is where the BDD feature files are located) is checked out at the same folder-level as this project.



### Linting



Two scripts are available to help you find linting errors:



```

npm run lint:check:all

```



This runs eslint in check mode which will raise errors found but not try and fix them. This is also ran on a PR and a push to main. It will fail if any errors were found.



```

npm run lint:write:all

```



This runs eslint in write mode which will raise errors found and try to fix them.