[Action required] API changes announcement for existing customers

Note: This announcement applies to API customers that are registered to a Prototype and Developer plans.

Hello all!

We are writing to inform you that a new set of plans is replacing our current application plans (Prototype and Developer plans) and prices.

As of 10th May 2022, the Prototype and Developer plans will no longer be operational. Oxford Dictionaries API will offer two new plans:

- Introductory plan
- Unlimited plan

For Prototype and Developer plan customers, changes are happening between 12th April 2022 and 10th May 2022. So do not worry! You will have time to check the options and choose how you wish to proceed using our data by selecting the Introductory or Unlimited plan.

For further instructions on how to change plans, and for more information, please visit our new plans announcement page.

Link: https://developer.oxforddictionaries.com/new-plans-announcement

If you have any questions, please feel free to leave us a comment or reach us at our Contact Us page. (https://developer.oxforddictionaries.com/contact-us)

The Oxford dictionaries API team

Client-side code generation

gatebuzzgatebuzz Member
edited March 2017 in General

An incredibly powerful feature of Swagger documentation is the ability to generate not just human readable live docs - https://developer.oxforddictionaries.com/documentation - but also all the code needed to talk to an API.

You will need at least Java 7 to run through this exercise.

Note: This full example is also available from my Github - https://github.com/psh/oxford-dictionary-api-code-gen - clone the repo and steps 1 -5 will already be done for you.

1. Download the Swagger code generation tool

At the time of writing this, swagger-codegen is at version 2.2.1 and can be obtained from http://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.2.1/swagger-codegen-cli-2.2.1.jar

2. Create a working directory

Create a working directory and copy the swagger-codegen-cli-2.2.1.jar into it. I am lazy, so I also renamed it to "swagger-codegen.jar" to save typing.

3. Check everything is ready to go

Check out the help built into Swagger codegen by typing

java -jar swagger-codegen.jar help

You should see a helpful message telling you about the options you have available. If you need a deeper-dive into Swagger codegen documentation, take a look at http://swagger.io/swagger-codegen/

4. Create an "output" directory

Swagger needs somewhere to place the generated client code and things just get messy if you generate 150 source files into the current directory!

5. Create a configuration file

For this example, I will generate a Java client to talk to the Oxford Dictionary API. The tool supports dozens of other languages and frameworks - take a look at the list by running

java -jar swagger-codegen.jar langs

The fictional project I am creating uses Retrofit v2 and RxJava, so my configuration file ("config.json") for Swagger will look like this:

{ "sourceFolder": "src", "modelPackage": "com.gatebuzz.oxford.model", "apiPackage": "com.gatebuzz.oxford.api", "library": "retrofit2", "useRxJava": true }

6. Run Swagger Codegen

I need to tell Swagger to

  • Generate a Java client
  • Configure itself from "config.json"
  • Read the Oxford Dictionary API docs
  • Write to the "output" directory I created

The command line is a little long, but looks like this (note: line continuation "\" characters have been inserted to aid clarity.)

java -jar swagger-codegen.jar generate \ --lang java \ -c config.json \ -o output \ -i https://developer.oxforddictionaries.com/swagger/spec/public_doc_guest.json

The tool is quite chatty as its reading files and creating code. When its finished you will have a working project in the "output" directory!

Comments

  • SimoneSimone Administrator admin
    edited January 2017

    Hi @gatebuzz !
    Many thanks for this, it will certainly be useful for a lot of people - it's great that you made it so clear.
    I'm making it sticky on the top of the discussion list.
    :smile:

  • vantipinvantipin Member

    Hi @gatebuzz,
    Thanks for pointing out link to swagger spec in your manual. We probably should add it to portal documentation.
    Anyway, a nice manual for Java developers.

  • gatebuzzgatebuzz Member

    Yes, the code generation tool uses Java, but the output can be any one of the available languages:

    $ java -jar swagger-codegen.jar langs
    
    Available languages: [android, aspnet5, async-scala, cwiki, 
    csharp, cpprest, dart, flash, python-flask, go, groovy, java, 
    jaxrs, jaxrs-cxf, jaxrs-resteasy, jaxrs-spec, inflector, javascript, 
    javascript-closure-angular, jmeter, nancyfx, nodejs-server, 
    objc, perl, php, python, qt5cpp, ruby, scala, scalatra, silex-PHP, 
    sinatra, rails5, slim, spring, dynamic-html, html, html2, 
    swagger, swagger-yaml, swift, tizen, typescript-angular2, 
    typescript-angular, typescript-node, typescript-fetch, 
    akka-scala, CsharpDotNet2, clojure, haskell, lumen, 
    go-server]
    

    It's one of the big benefits of providing us Swagger docs! :smile:

Sign In or Register to comment.