apicollective / apibuilder-cli Goto Github PK

View Code? Open in Web Editor NEW

84.0 9.0 20.0 448 KB

Command line interface to apibuilder

License: MIT License

Ruby 99.70% Shell 0.30%

apibuilder-cli's Introduction

apibuilder-cli

Command line interface to API Builder

Install

On MacOS using brew:

brew install apibuilder-cli

For other platforms:

sudo ./install.sh /usr/local

Setup for public APIs

No setup needed - just use the API Builder command directly (see below)

Setup for private APIs

Run bin/create-config and follow the instructions. This will walk you through the following steps:

Create a token for your user account
Create a configuration file in ~/.apibuilder/config Example File:
```
 [default]
 token = <your API token>
```
Verify that your configuration file is valid:
```
 bin/read-config
```

Commands

list

List all organizations that you have access to:

bin/apibuilder list organizations

List all applications that belong to a specific organization:

bin/apibuilder list applications <organization key>

List all versions of a particular application

bin/apibuilder list versions <organization key> <application key>

Note since the GET requests in API Builder are paginated, you might need to paginate. Where pagination is required, we use two environment variables: LIMIT, OFFSET

LIMIT=10 OFFSET=10 bin/apibuilder list organizations

code

Invoke a code generator from the command line

bin/apibuilder code <organization key> <application key> <version> <generator> <target dir> [<filename> ...]

For example, to generate a play 2.6 client for the latest version of apibuilder itself:

bin/apibuilder code apicollective apibuilder-api latest play_2_6_client .

Each code generator returns a list of files. To download a specific file:

bin/apibuilder code apicollective apibuilder-api latest play_2_6_client . [<filename> ...]

For example:

bin/apibuilder code apicollective apibuilder-api latest http4s_0_17 . ApicollectiveApibuilderApiV0Client.scala ApicollectiveApibuilderApiV0Server.scala

The file names support wildcard expansion (? for a single character, * for zero or more), e.g:

bin/apibuilder code apicollective apibuilder-api latest http4s_0_17 . *ApiV?Client*.scala

To view a list of available generators visit apibuilder.io/generators

upload

Upload a new version of an api given the json descriptor.

bin/apibuilder upload <organization key> <application key> <file> --version <version> [--force] [--silent] [--update-config <optional path>]

For example:

bin/apibuilder upload apicollective apibuilder-api apibuilder-api/api.json --version 1.0.1

The --force flag will allow you to re-upload an api.json even if there are no changes since the previously uploaded version.

When using the --silent flag, the suggested tag will be automatically used. This is useful for automated uploading via git hooks and/or CD pipelines.

The --update-config flag tells the cli to update the local .apibuilder/config with the new version of the given api. It uses either the default path or the path given in the argument.

update

Invoke code generator based on configuration stored in a local file:

bin/apibuilder update [--path path] [--org org-name] [--app project-name]

    path defaults to `.apibuilder/config` in the current directory. Note that this file
    should contain only the parameters needed to identify which code generators to
    invoke and is independent from the global `~/.apibuilder/config` file where you
    store your token.

    Specifying `--org` will limit the update to only projects within that org;
    all code generated from other orgs will remain untouched. Can be combined with
    `--app` but not required.

    Specifying `--app` will limit the update to only projects that match the given name;
    all code generated from other projects will remain untouched. Can be combined with
    `--org` but not required.

The configuration file is a YAML file that follows the convention:

command:
  org:
    project:
      version: <version>
      generators:
        <generator name 1>:
          target: <path to directory or specific filename>
        <generator name 2>:
          target: <path to directory or specific filename>
          files: <file name or file pattern>
        <generator name 3>:
          target: <path to directory or specific filename>
          files:
            - <file name or file pattern>
            - <file name or file pattern>

Example File:

code:
  apicollective:
    apibuilder:
      version: latest
      generators:
        play_2_6_client:
          target: generated/app
        play_2_x_routes:
          target: api/conf/routes
          files: apicollective*.*
    apibuilder-spec:
      version: latest
      generators:
        play_2_6_client:
          target: generated/app
          files:
            - apicollective*.*
            - '*client.rb'
    apibuilder-generator:
      version: latest
      generators:
        play_2_6_client: generated/app

Note: Previously the configuration file syntax did not specify any files and instead specified the path as the value of the generator name. While still supported, this syntax is deprecated:

command:
  org:
    project:
      version: <version>
      generators:
        <generator name>: <path to directory or specific filename>

If the same generator needs to be invoked multiple times for different target directories, the YAML file can have the following alternate syntax:

command:
  org:
    project:
      version: <version>
      generators:
        - generator: <generator name>:
          target: <path 1>
          files:
            - <file name or file pattern>
        - generator: <generator name>:
          target: <path 2>
          files:
            - <file name or file pattern>

In addition, you can specify global settings for how the client behaves:

Example File w/ Settings:

settings:
  code.create.directories: true

code:
  apicollective:
    apibuilder:
      version: latest
      generators:
        play_2_6_client: generated/app

Supported settings include:

code.create.directories: Defaults to false. If true, when you run apibuilder update, we will create the subdirectories as specified by the code generator.

You can also specify attributes to pass in to the code generators (both global and local), including the use of a wildcard to select multiple generators to which to apply the attributes:

Example File w/ Global Generator Attributes:

attributes:
  generators:
    foo*:
      key: value
    play_2_6_client:
      foo: bar

code:
  apicollective:
    apibuilder:
      version: latest
      generators:
        play_2_6_client: generated/app

Example File w/ Local Generator Attributes:

code:
  happycorp:
    api-salary-calculator:
        version: 1.3.5
        generators:
          - generator: play_2_6_client
            target: src/test/generated
            attributes:
              foo: baz
            files:
              - HappycorpApiSalaryCalculatorV0MockClient.scala

Supported attributes are defined by each code generators.

clean

Delete versions in ApiBuilder that are not tagged in the source repo.

bin/apibuilder clean <organization key> <application key> [--branch <branch name>] [--silent] [--legacy]

For example:

bin/apibuilder clean apicollective apibuilder-api --branch dev

When using the --silent flag, the suggested versions will be automatically deleted without prompting. This is useful for automated cleanup via git hooks and/or CD pipelines.

If you have versions that use the legacy default naming (i.e. that match the pattern /^.*-\d+-g[0-9a-f]{7}$/) and belong on a non-master branch, use the --legacy flag to interactively move those versions to the proper branch. You only need to run this once, at the point of migrating from the legacy naming to the branch naming. Afterwards, simply run clean without the --legacy flag.

cli itself

Display the current version of the CLI.

bin/apibuilder cli version

Display the latest available version of the CLI.

bin/apibuilder cli latest

Upgrade to the latest version

bin/apibuilder cli upgrade

Environment Variables

PROFILE: Select a specific profile to use, read from the .apibuilder/config
         configuration file

APIBUILDER_TOKEN: If specified, this is the apibuilder token we use

To setup a configuration profile, add a section to ~/.apibuilder/config for each profile:

[default]
token = xxx

[profile localhost]
api_uri = http://localhost:9001
token = yyy

apibuilder-cli's People

Contributors

Stargazers

Watchers

Forkers

seanstoppable paololim kalmanb mikeclimbrock benwaffle gambtho gheine amarrella barambani flowcommerce jkenny arrodriguez darrenmc ctumolosus f-zou mkows brianmlima dawidd6

apibuilder-cli's Issues

Cannot override api url

According to the apibuilder documentation, you should be able to use the env var APIBUILDER_API_URI to override the API that is hit

.tracked_files uses absolute paths

e.g:

---
flow:
  api:
    ruby_client:
    - "/web/flowmisc/billing/lib/flow_commerce/flow_api_v0_client.rb"
  api-internal:
    ruby_client:
    - "/web/flowmisc/billing/lib/flow_commerce/flow_api_internal_v0_client.rb"

So if a different user has a different project location, this might not delete all files, or might delete extra files that are needed.

apibuilder update --app breaks .tracked_files

when you run apibuilder update --app <whatever> it removes any other generated files from .tracked_files. only the file that was just updated remains tracked

Should not stop code generation when generator does not respond with a recommended directory

When I enable directory creation in the global settings, the CLI exits with no implicit conversion of nil into String for generators that do not respond with a recommended directory path. A recommended directory is an optional field of the file model, thereby the CLI should gracefully fallback to no directory creation.

settings:
  code.create.directories: true

CLI doesn't download different versions of generated code for the same API

When running apibuilder update with a config like below (note the same api declared with different versions) only the files for the version declared latest are downloaded:

my-api:
  version: 1.0.3
  generators:
    - ...
my-api:
  version: 2.0.0
  generators:
    - ...

implement apibuilder update --help

create-config does not work from brew install

after brew install apibuilder-cli:
When running /opt/homebrew/bin/create-config I get
/opt/homebrew/bin/create-config:9:in load': cannot load such file -- /opt/homebrew/bin/../src/apibuilder-cli.rb (LoadError) from /opt/homebrew/bin/create-config:9:in

'
It seems to expect the source code but brew doesn't have that installed, so I manually made the credentials file and it worked for private apibuilder projects after that.

Also it seems like apibuilder-cli wasn't added to my path after brew install

Can I use the CLI in an offline fashion?

Or does it always have to connect to the website?

Missing documentation

The output of running apidoc in terminal is as follows:

$ apidoc                                                                                                               [14:16:50]
** ERROR: Missing command is required. Available commands:
 - cli
 - code
 - download
 - example
 - list
 - update
 - upload

However, only the following are documented: list, code, and update. Running apidoc upload yields a cryptic error to anyone unfamiliar with the tool:

$ apidoc upload                                                                                                        [14:17:40]
org, application, path are required

It would be great if apidoc --help returned some more information w/ specific examples.

Accept string representing regex to filter generated files without modification

It's unclear to me which syntax the CLI wants me to use to filter files. It looks like it wants to support globs, but the implementation to turn a glob into a regular expression feels incomplete. At least, I could not find a way to exclude a single file by name. Since the patterns that can be used are poorly documented and feel limited by the implementation, I propose the file filter should accept a regular expression without substitution. In my case, this would allow me to exclude a single file using a negative lookahead ^(?!filename).*\.js$.

Basically, I'm proposing this line is changed from:

file_regex = Regexp::new("^" + filename.gsub('.', '\.').gsub('*', '[^.]*').gsub('?', '[^.]?') + "$")

to:

file_regex = Regexp::new(filename)

pulling resources from cli stopped working

For example:

http://apidoc.me/gilt/api-user-registration/0.0.2/play_2_x_routes used to return contents of the routes file, and with it this command...

$ /web/apidoc-cli/bin/apidoc code gilt api-user-registration 0.0.2 play_2_x_routes

... used to pull contents of routes.

But now that generators could contain multiple files, routes live at: http://apidoc.me/gilt/api-user-registration/0.0.2/play_2_x_routes/routes

and, seemingly, with this change cli command returns a listing of files

$ /web/apidoc-cli/bin/apidoc code gilt api-user-registration 0.0.2 play_2_x_routes
play_2_x_routes Files:
 - routes

Option to download a zip file

Need a way to download a zip file, for example from here: http://apidoc.me/gilt/checkout-api/latest/android_client (generator takes ~2 minutes to warm up on lambda, so if you get an error on that page - try again after ~2 minutes)

List more than one directory for the input

How can I list more than one directory for the input?
I want to tell apidoc to look in 2 directories, for example:

apidoc --input dir1/ dir2/

Can't download just one file from a generator

Currently it does not seem to be possible to download just a single file from a given generator. See e.g. https://app.apibuilder.io/apicollective/apibuilder-generator/0.12.58/http4s_0_15
With the http4s generator I will always only need one of the generated files, never all. Sepcifying the following in the .apibuilder file gives the error below:

      generators:
        http4s_0_15: src/main/scala/generated/ApicollectiveApibuilderGeneratorV0ModelsJson.scala

Fetching code from https://api.apibuilder.io
  apicollective/apibuilder-generator/latest/http4s_0_15...
/Users/gheine/.rvm/rubies/ruby-2.3.1/lib/ruby/2.3.0/fileutils.rb:253:in `mkdir': File exists @ dir_s_mkdir - /Code/src/main/scala/generated/ApicollectiveApibuilderGeneratorV0ModelsJson.scala (Errno::EEXIST)
	from /Users/gheine/.rvm/rubies/ruby-2.3.1/lib/ruby/2.3.0/fileutils.rb:253:in `fu_mkdir'
	from /Users/gheine/.rvm/rubies/ruby-2.3.1/lib/ruby/2.3.0/fileutils.rb:227:in `block (2 levels) in mkdir_p'
	from /Users/gheine/.rvm/rubies/ruby-2.3.1/lib/ruby/2.3.0/fileutils.rb:225:in `reverse_each'
	from /Users/gheine/.rvm/rubies/ruby-2.3.1/lib/ruby/2.3.0/fileutils.rb:225:in `block in mkdir_p'
	from /Users/gheine/.rvm/rubies/ruby-2.3.1/lib/ruby/2.3.0/fileutils.rb:211:in `each'
	from /Users/gheine/.rvm/rubies/ruby-2.3.1/lib/ruby/2.3.0/fileutils.rb:211:in `mkdir_p'
	from /web/apidoc-cli/bin/apibuilder:371:in `block (4 levels) in <main>'
	from /web/apidoc-cli/bin/apibuilder:365:in `each'
	from /web/apidoc-cli/bin/apibuilder:365:in `block (3 levels) in <main>'
	from /web/apidoc-cli/bin/apibuilder:360:in `each'
	from /web/apidoc-cli/bin/apibuilder:360:in `block (2 levels) in <main>'
	from /web/apidoc-cli/bin/apibuilder:359:in `each'
	from /web/apidoc-cli/bin/apibuilder:359:in `block in <main>'
	from /web/apidoc-cli/bin/apibuilder:358:in `map'
	from /web/apidoc-cli/bin/apibuilder:358:in `<main>'

Prompt user to update when necessary

enable ability to ask users to update their CLI

add travis ci

needs to run rspec test/spec/lib/*

Alias error with Ruby 3.1.1

Hi guys,
I'm trying to add a variable in the YAML file in order to reuse it in some points in the same file.

code:
  org:
    service-one:
      version: *version
      generators:
        dart_2_17_json:
          target: source

Running the command apibuilder update --path .apibuilder.yml it works running it on a macOS with ruby version 2.6.10 but it doesn't work running it on a macOS with ruby version 3.1.1.

/Users/federico/.rbenv/versions/3.1.1/lib/ruby/3.1.0/psych/visitors/to_ruby.rb:430:in `visit_Psych_Nodes_Alias': Unknown alias: version (Psych::BadAlias)

Searching I found this possible issue but I'm not sure.
https://stackoverflow.com/questions/71191685/visit-psych-nodes-alias-unknown-alias-default-psychbadalias

Do you have any idea how I can solve it keeping the latest ruby version?
Thanks

$ brew install apibuilder-cli
==> Downloading https://github.com/apicollective/apibuilder-cli/archive/0.1.25.tar.gz
Already downloaded: /Users/gary/Library/Caches/Homebrew/apibuilder-cli-0.1.25.tar.gz
==> ./install.sh /usr/local/Cellar/apibuilder-cli/0.1.25
🍺  /usr/local/Cellar/apibuilder-cli/0.1.25: 19 files, 305.6KB, built in 2 seconds

$ apibuilder
/usr/local/bin/apibuilder:68:in `load': cannot load such file -- /usr/local/bin/../src/apibuilder-cli.rb (LoadError)
	from /usr/local/bin/apibuilder:68:in `<main>'

There seem to be two loads of the above file:

load File.join('/usr/local/Cellar/apibuilder-cli/0.1.25/src/apibuilder-cli.rb')
#  - Upgrade the CLI to the latest version
#

load File.join(File.dirname(__FILE__), '../src/apibuilder-cli.rb')

apicollective / apibuilder-cli Goto Github PK

apibuilder-cli's Introduction

apibuilder-cli

Install

Setup for public APIs

Setup for private APIs

Commands

list

code

upload

update

clean

cli itself

Environment Variables

apibuilder-cli's People

Contributors

Stargazers

Watchers

Forkers

apibuilder-cli's Issues

Recommend Projects

Recommend Topics

Recommend Org