Third Party Developer Blog

Aug

Setting up and Running esi-swagger-ui: ESI's Newly Open Sourced Front End

CCP Zoetrope | 2017-08-08 14:20

This blog post is part of a series of blogs examining best practices for ESI development. Each blog will be published on the 8th of each month during the journey towards XML API and CREST’s termination date. The legacy APIs will be terminated on May 8th, 2018, or earlier if metrics signal a trivial level of usage.

On July 11th, Team Tech Co open sourced the repository behind ESI's user interface: esi-swagger-ui. In doing so, we wanted to provide a way to the community to have documentation available offline as well as giving the community a chance to contribute and make ESI better looking and easier to use.

esi-swagger-ui is a fork of the official swagger-ui project and is built on version 3 of that project. At the time of this writing, the default view for ESI is still using swagger-ui version 2 at https://esi.tech.ccp.is, but you can see a live running instance of the ESI documentation using swagger-ui version 3 at https://esi.tech.ccp.is/ui/. This will be the case until version 3 has a few bugs worked out.

This blog will focus on getting set up and running esi-swagger-ui locally as well as offering a few development tips. Because a big step in setting up the repository is dependent on bash then it is assumed the reader is running a Unix based system. However, running the UI itself is done using Docker so a Windows user could manually do the steps found in run.sh. In fact, feel free to make the setup process easier for Windows users and make a pull request!

Prerequisites

Docker needs to be installed and running. Look here for more info on what Docker is.
Git so that you can clone the repository.
A Github account.

Setting up your environment to run esi-swagger-ui

There are four things we are going to walk you through that you will need to run esi-swagger-ui:

You need to know the IP address or URL your Docker daemon uses and set the environment variable DOCKER_MACHINE_NAME to that value.
You need an EVE third party application with all scopes enabled and the callback URL http://{your-docker-host}:8000/ui/oauth2-redirect.html where {your-docker-host} is the IP or URL for your Docker daemon.
You need a fork of the esi-swagger-ui Github repository cloned to your workstation.
You need a local file in the same repo named client_id that contains your third party application's client ID.

Finding and setting Docker's host

The following instructions were tested on Ubuntu 16.04

Finding Docker's IP

If Docker was set up correctly there should be a network interface named docker0 that will show you what IP Docker is using. Try running the command

ifconfig docker0

Look for inet addr, the IP address listed after is the docker host. A common CIDR for Docker is 172.17.0.0/32.

To give Docker a host name, edit your /etc/hosts file and append the following line (except using your Docker's IP address):

172.17.0.1  docker.local

After saving and exiting you now should be able to access the Docker daemon by using docker.local. Quickly test that this is the case by doing

ping docker.local

Setting DOCKER_MACHINE_NAME

Now that you know Docker's IP or have set it to be docker.local it is now time to set the environment variable DOCKER_MACHINE_NAME. Use the following command to set this:

export DOCKER_MACHINE_NAME=docker.local

Replace docker.local with Docker's IP if you did not set Docker's hostname to docker.local. If you want DOCKER_MACHINE_NAME to be available all the time, place the previous export command into your .bashrc or equivalent if not using bash and then refresh your session by logging out and in.

To see that DOCKER_MACHINE_NAME was set correctly use the following command:

echo $DOCKER_MACHINE_NAME

and you should see Docker's host or IP address displayed.

Creating a third party application with all scopes and the correct callback URL

Go to https://developers.eveonline.com and login.
Go to applications and click "Create new application".
After putting a name and description, in "Connection Type" choose "Authentication & API Access".
Have a clicking party with the scopes until they're all in the "Requested Scopes List".
For the callback URL you will have to remember the Docker host from the previous section. Given Docker host docker.local the callback URL should be http://docker.local:8000/ui/oauth2-redirect.html. Replace docker.local with whatever your Docker host is.
Click "Create Application".

Now you should have a third party application that uses all scopes.

Forking and cloning the repository

Navigate to https://github.com/ccpgames/esi-swagger-ui in your browser and click on "Fork" in the upper right corner. When asked where the repository should be forked to, click on your Github account. Once the forking has been completed you should be looking at a web page with your forked repository. You'll know it's yours if the name of the repository has your github username in it (for instance mine is ccp-zoetrope/esi-swagger-ui).

After you've done that follow this guide and do steps 2 and 3 to get your fork cloned locally onto your work station and also synced with the original ccpgames/esi-swagger-ui repo.

Using your client ID with esi-swagger-ui

With https://developers.eveonline.com/applications open, find the application you created previously and click on "View Application". Find the client ID and copy it to the clipboard.

Go back to your terminal and make sure you are in the root of the forked repository you just cloned. Once there, you need to put your client ID into a file called client_id (there should be no filetype ending). Do this by using a text editor or running the following command:

echo "{your-client-id}" > client_id

where {your-client-id} should be replaced by your application's client ID. Once that's done you should be ready to run everything!

Running esi-swagger-api

Still in the root of your forked repository, do the following command:

./run.sh

and it will do the following things:

Fetch the latest, dev and legacy ESI Swagger specs and store them on your local machine under the directories latest/, legacy/ and dev/.
Build a Docker image that uses your client ID.
Stop the current running esi-swagger-ui Docker container if it is running.
Run the newly built image inside a Docker container.

If you want to know more details about what is happening then feel free to dig into the files run.sh and Dockerfile.

To check if it is successfully running, do the command

docker ps

and you should see output similar to:

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES
d8dc8c278619        esi-swagger-ui-v3   "sh /usr/share/ngi..."   9 minutes ago       Up 9 minutes        0.0.0.0:8000->8080/tcp   esi-swagger-ui-v3

Now, go to your browser and navigate to http://{your-docker-host}:8000/ui and you should see the ESI documentation appearing before your eyes.

Updating to the latest ESI spec

This version of ESI's UI is not dynamically generated like the UI on https://esi.tech.ccp.is but instead downloads a local copy of the latest, dev and legacy specs. Because of this you need to manually update these specs to see the latest changes. To do that, simply delete the latest/, dev/ and legacy/ directories that were created when you ran esi-swagger-ui and re run it using run.sh. This should re-download the most up to date Swagger spec for ESI.

Contributing

Now that you have ESI's UI running locally you can start hacking away and contribute! Here in Team Tech Co we follow the "Fork-and-Branch" Git workflow for contributions. Here is a detailed walkthrough of this Git workflow that should help you contribute. If you've never contributed to an open source project before here is a great rundown of how to actually contribute to open source projects. If you have an idea for how to improve the ESI UI then please don't hesitate to contribute!

To make sure your time is well spent please open an issue in the esi-swagger-ui Github project to discuss the changes you would like to make before actually implementing anything. This way you can know if we also agree with your proposed changes and would like you to move forward with them. Changes submitted to the repository will also need to be accompanied by a signed Contributors License Agreement and we will arrange to have these dispatched to contributors as the final stage of approving a pull request. Our CLA looks like this, but may be subject to change.

Appendix

Since the last blog, the following XML API endpoints have been ported to ESI:

category	XML endpoint	ESI parity
char
.	CharacterSheet	https://esi.tech.ccp.is/latest/#!/Character/get_characters_character_id_fatigue (This was added on top of what's already there for parity with the XML endpoint)
.	Clones	https://esi.tech.ccp.is/latest/#!/Clones/get_characters_character_id_implants
eve
.	FacWarStats	https://esi.tech.ccp.is/latest/#!/Faction32Warfare/get_fw_wars https://esi.tech.ccp.is/latest/#!/Faction32Warfare/get_fw_stats

The following ESI endpoint's versions have been bumped since the last blog:

GET /latest/corporations/{corporation_id}/alliancehistory/ (v2)
GET /dev/characters/{character_id}/clones (v3)
GET /dev/universe/types/{type_id} (v3)
GET /latest/universe/system_kills/ (v2)
GET /latest/dogma/effects/{effect_id} (v2)
GET /latest/characters/{character_id}/planets/{planet_id}/ (v3)

Complete and up-to-date list can be found here.

CCP Zoetrope

back