autogenerate client sdk from swagger definition

[jbjonesjr]

What's up?

The existing/POC API GSA/code-gov-api-client is out of date, and instead of trying to update it, you're probably better off generating an entirely new client, based on your existing swagger documentation.

What am I looking for

Configuring some sort of client generation process into the build pipeline for this application that will also keep a modern client up to date.

Alternatives?

Rewriting the existing API client to be up to date. But it doesn't even know about API_KEY, let alone all the current endpoints and params. This also seems like a losing battle as the api and site evolve 🤞

Additional context

Mucked around with this: https://www.npmjs.com/package/swagger-node-codegen
But I think it only generates a server based on a swagger def

This looks like a thing (https://app.swaggerhub.com/help/apis/generating-code/client-sdk), but i'm not installing a desktop app for this.

This seems like exactly what I want (https://github.com/swagger-api/swagger-codegen/wiki/FAQ), but like hell am I installing maven and java on this computer just for this task.

So, what am I really doing? Hoping yall will do me a solid and build this thing for me in exchange for me doing the leg work.

[DanielJDufour]

Awesome idea!

[froi]

First, more issues like this, please. 😄

I like the idea of having the API build process create the client. We didn't think of this but makes a ton of sense.

Let's go over a couple of things with the API.

1. API_KEY:
   TLDR - we don't manage the API key generation and authorization.

   We are using api.data.gov to handle key generation and authorization for us. We understand that this complicates things when creating an API client and makes the API code look out of date. For now what we can do is make sure that our docs reflect this fact as to not create (more like manage) confusion.

2. The options and params.
   This is my fault. All the search options and parameters have not been documented correctly. I will make the effort to document this correctly.

We'll take a look at the links you posted and see what we can fit into our current roadmap.

Thanks again!

[jbjonesjr]

API KEY

I don't think the API key thing is a big deal (who owns it, etc), just generating the client new CodeGovAPI or whatever should take the api key as a param. In playing with the existing/old client, i retrofitted the constructor to take the api key and then append it as a query param to the methods called.

Roadmap

ugh. i'll regret this later, but.... I'd probably be willing to open source assist in this. time box it to a few hours and i'll execute on it.

[mikewlange]

This is the open source project you want to use; https://github.com/go-swagger/go-swagger It's exactly what you're looking for. Run it in docker.

NOTE: I have not used this package. But software written in golang is usually of high quality.

Go compiles into a binary that runs anywhere. Combine that with the flexibility of docker and you're golden.

// command line..
docker pull quay.io/goswagger/swagger
alias swagger="docker run --rm -it -e GOPATH=$HOME/go:/go -v $HOME:$HOME -w $(pwd) quay.io/goswagger/swagger"
swagger version

Now you are in the command line of the docker image.

Then you can:

(I copied and pasted below from their repo) Good Luck!!

Installing

go-swagger is available as binary or docker releases as well as from source: more details.

Use-cases

The main package of the toolkit, go-swagger/go-swagger, provides command line tools to help working with swagger.

The toolkit is highly customizable and allows endless possibilities to work with OpenAPI2.0 specifications.

Beside the go-swagger CLI tool and generator, the go-openapi packages provide modular functionality to build custom solutions on top of OpenAPI.

The CLI supports shell autocompletion utilities: see here.

Serve specification UI

Most basic use-case: serve a UI for your spec:

swagger serve https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-expanded.json

Validate a specification

To validate a Swagger specification:

swagger validate https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-expanded.json

Generate an API server

To generate a server for a swagger spec document:

swagger generate server [-f ./swagger.json] -A [application-name [--principal [principal-name]]

Generate an API client

To generate a client for a swagger spec document:

swagger generate client [-f ./swagger.json] -A [application-name [--principal [principal-name]]

Generate a spec from source

To generate a swagger spec document for a go application:

swagger generate spec -o ./swagger.json

Generate a data model

To generate model structures and validators exposed by the API:

swagger generate model --spec={spec}

Transform specs

There are several commands allowing you to transform your spec.

Resolve and expand $ref's in your spec as inline definitions:

swagger expand {spec}

Flatten your spec: all external $ref's are imported into the main document and inline schemas reorganized as definitions.

swagger flatten {spec}

Merge specifications (composition):

swagger mixin {spec1} {spec2}

Compare specs

The diff command allows you to check backwards compatibility.
Type swagger diff --help for info.

swagger diff {spec1} {spec2}

Try it

Try go-swagger in a free online workspace using Gitpod: