potential refactor in a section on how to generate a client library

[dmitrij-schmidt]

if somebody would like to skip API client generation step and hop straight to game client development, more explicit step on how to generate an API client may be useful:

1. visit https://spacetraders.stoplight.io/docs/spacetraders
2. head to SpaceTraders API, on the top right side Export -> Bundled references(!). copy resulting URL
3. run curl -X GET "http://api.openapi-generator.tech/api/gen/servers" -H "Accept: */*", pick whatever language/framework you need
4. run curl -X POST -H "content-type:application/json" -d '{"openAPIUrl":"LINK_TO_BUNDLED_JSON"}' http://api.openapi-generator.tech/api/gen/servers/FRAMEWORK
5. download package from the link provided to curl request

NOTE: if you want to try it with JS/TS or other languages potentially not supported by OpenAPI generator, copy JSON content from step 2, paste it into https://editor-next.swagger.io/ and select Generate Client option in the top menu.

[space-admiral]

This looks great, we'll add this to the docs under client generation.

[galdor]

I cannot find any "Export" or "Bundled references" entry anywhere on https://spacetraders.stoplight.io/docs/spacetraders, did something change?

It would be useful to add a direct link to a single-file OpenAPI specification (lots of OpenAPI tools do not work well with references between multiple files) in the documentation.

Edit:

Found it! It is available at https://stoplight.io/api/v1/projects/spacetraders/spacetraders/nodes/reference/SpaceTraders.json?fromExportButton=true&snapshotType=http_service&deref=optimizedBundle

Careful, the "v1" on Stoplight is actually the "v2" of SpaceTraders.

[jonchurch]

Hey specifically the snippet on the docs site for generating a client does not work anymore with openapi-generator-cli, their v2 version has a different name.

I didn't see the source anywhere for this specific doc page though? https://docs.spacetraders.io/api-guide/open-api-spec

This command can be updated to:

# # Execute the openapi-generator-cli using npx (requires that Node.js is installed)
# npx openapi-generator-cli generate \
#  # Set the input file URL containing the OpenAPI specification JSON
#  # you can also point it to a local input file, but this makes sure we get
#  # the latest version every time we run this command
#  -i https://raw.githubusercontent.com/SpaceTradersAPI/api-docs/main/reference/SpaceTraders.json \
#  # Set the output directory for the generated SDK
#  -o packages/spacetraders-sdk \
#  # Set the generator type to generate the TypeScript-Axios client
#  # (find the desired language/HTTP client combo at https://openapi-generator.tech/docs/generators/)
#  -g typescript-axios \
#  # The rest of these "additional-properties" are arguments passed to the specific generator you selected above
#  # see the docs for your selected generator for information about additonal-properties
#  # Set the npm package name to "spacetraders-sdk"
#  --additional-properties=npmName="spacetraders-sdk" \
#  # Set the npm package version to "2.0.0"
#  --additional-properties=npmVersion="2.0.0" \
#  # Enable ES6 support in the generated SDK
#  --additional-properties=supportsES6=true \
#  # Generate separate files for models and API
#  --additional-properties=withSeparateModelsAndApi=true \
#  # Set the package name for models
#  --additional-properties=modelPackage="models" \
#  # Set the package name for API
#  --additional-properties=apiPackage="api"
npx openapi-generator-cli generate \
 -i https://raw.githubusercontent.com/SpaceTradersAPI/api-docs/main/reference/SpaceTraders.json \
 -o packages/spacetraders-sdk \
 -g typescript-axios \
 --additional-properties=npmName="spacetraders-sdk" \
 --additional-properties=npmVersion="2.0.0" \
 --additional-properties=supportsES6=true \
 --additional-properties=withSeparateModelsAndApi=true \
 --additional-properties=modelPackage="models" \
 --additional-properties=apiPackage="api"

The diff is:

• extensive commenting by gpt-4
• added npx so users do not have to install the generator to run it
• updated to the V2 command name openapi-generator-cli
• Updated the input file to reference the github raw link of the SpaceTraders.json (will always be latest version of API spec)

[jonchurch]

The example code at the bottom of the OpenAPI section of the docs is using a v1 spacetraders client btw (but I also think the code example is incorrect, it exports a class not named exports) https://www.npmjs.com/package/spacetraders-sdk

import axios from 'axios'
import {
  Configuration,
  Cooldown,
  DefaultApi,
  FleetApi,
  SystemsApi
} from 'spacetraders-sdk'

export const configuration = new Configuration({
  basePath: process.env.BASE_PATH,
  accessToken: process.env.ACCESS_TOKEN
})

export const instance = axios.create({})

// example retry logic for 429 rate-limit errors
instance.interceptors.response.use(undefined, async (error) => {
  const apiError = error.response?.data?.error

  if (error.response?.status === 429) {
    const retryAfter = error.response.headers['retry-after']

    await new Promise((resolve) => {
      setTimeout(resolve, retryAfter * 1000)
    })

    return instance.request(error.config)
  }

  throw error
})

const system = new SystemsApi(configuration, undefined, instance)

system.getSystems().then(console.log)

It could be swapped out for a community member's axios based openapi generated client. https://www.npmjs.com/package/spacetraders-api

The code would be almost the same except for the last line:

system.getSystems().then((response) => console.log(response.data.data))

The example code is a bit superfluous, doesn't need to export the configuration object or the axios instance, that endpoint no longer requires auth, and there's not a real reason for a user in a quickstart guide to reset the base path.