Swagger is pretty cool API specification format where you describe a REST endpoint using either JSON or YAML. For lots of languages it is possible to generate both documentation, interfaces, a GUI testing endpoint, and client libs from from these documents.
There is an online service (apimatic) who perform this task - but they do not yet generate Elixir source code.
Perhaps there is an existing mix or phoenix generator to perform the task of generating client libs but I can’t find anything that seems suitable.
Any suggestions? I’m willing to open up the Chris McCord macro programming book if necessary.
3 Likes
Swagger Ain’t REST - is that OK? (Reddit)
The problems with Swagger
Now there may be numerous reasons why somebody may want a Swagger style API - but once you get past the realization that Swagger actually isn’t REST, it has to compete with all the other non-REST API styles. And it seems that currently the momentum in the Elixir/Phoenix space for new APIs is with GraphQL.
Now that doesn’t mean people wouldn’t be interested in a code generator to help with consuming existing Swagger-based API’s (i.e. Elixir Swagger clients).
Anyway, that’s just one (my) opinion.
1 Like
GraphQL is a great idea and good for social media type apps - but I’m looking for simple HTTP RPC to business services that someone else has already written 
And I am lazy. If I’m going to be trying out a load of these API’s I don’t want to have to hand crank a client implementation every time - I’m thinking scaffolding.
I mean I could write an Elixir code generator using PyParsing but I’m all about the Elixir these days - if there’s an elegant way to perform this chore using macros or whatever I’m all ears.
Noooooo no RPC please…
Anyway, the Swagger codegen are horrendous and the advice you will find everywhere is to just use Swagger as a doc and to code your API wrapper around it by yourself. In nearly all languages.
I know that because a lot of the “ok-ish not too bad” generators are to this state because the Eve Online community had to rewrite and PR for them when Eve Online new API moved to Swagger… They stopped trying after the first month and just wrap it all “by hand” (except maybe the Scala one).
Swagger in general is pretty awful.
Also please please please do not do HTTP RPC. Thanks. There are enough jobs out there that we can force people using that to have their code rot of being unmaintained…
Used swagger-codegen-cli docker image to perform the code generation from a swagger file generated from the original apiary blueprint via apimatic
docker network create foo
docker run -h server --name=server --network=foo --rm -v $(pwd):/var/www:ro -p 8080:8080 trinitronx/python-simplehttpserver
docker run --network=foo --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate -i http://server.foo:8080/apiary.yml -l elixir -o /local/elixir
[main] INFO io.swagger.parser.Swagger20Parser - reading from http://server.foo:8080/apiary.yml
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/allocation.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/billingAddressAttributes.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createACustomerRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createACustomerResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createADeliveryMethodRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createADeliveryMethodResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createANewAllocationRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createANewAllocationResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createANewOrderNoteRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createANewOrderNoteResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createANewOrderRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createANewOrderResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createANewProductRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createANewProductResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createANewSupplierRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createANewSupplierResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createANewTagRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createANewTagResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createAShipmentRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createAShipmentResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createAStoreRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createAStoreResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createAWarehouseRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/createAWarehouseResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/imagesAttributes.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/listAllCustomersResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/listAllDeliveryMethodsResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/listAllOrdersResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/listAllProductsResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/listAllPurchaseOrdersResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/listAllStoresResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/listAllSuppliersResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/listAllTagsResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/listAllWarehousesResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/note.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/productVariantsAttributes.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/shipment.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/status.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/stockEntry.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/trackingNumberAttributes.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/typeCode.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/updateAStockEntryRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/updateAStockEntryResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/updateAllocationDetailRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/updateCompanyDetailRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/updateCustomerDetailRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/updateDeliveryMethodDetailRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/updateOrderDetailRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/updateProductDetailRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/updateStoreDetailRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/updateSupplierDetailRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/updateWarehouseDetailRequest.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/viewASupplierDetailResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/viewAnOrderDetailResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/viewAnTagDetailResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/viewCompanyDetailResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/viewCustomerDetailResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/viewDeliveryMethodDetailResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/viewProductDetailResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/viewStoreDetailResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/model/viewWarehouseDetailResponse.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/api/allocations.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/api/company.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/api/customers.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/api/deliveryMethods.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/api/orderNotes.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/api/orders.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/api/products.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/api/purchaseOrders.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/api/shipments.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/api/stockEntries.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/api/stores.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/api/suppliers.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/api/tags.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/lib/veeqo_api_(beta)/api/warehouses.ex
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/README.md
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/config/config.exs
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/mix.exs
[main] INFO io.swagger.codegen.AbstractGenerator - writing file /local/elixir/test/test_helper.exs
The Generated client uses Tesla HTTP client library. Generator is written in Java.
On first glance it seems pretty sane, the package directory naming (veeqo_api_(beta)) needs to be tweaked of course - I did so by editing the title yaml element.
Anyway, the Swagger codegen are horrendous and the advice you will find everywhere is to just use Swagger as a doc and to code your API wrapper around it by yourself. In nearly all languages.
Not sure when is the last time you tried Swagger Codegen, which has made a lot of improvements in recent years thanks to the vibrant community. We just released stable version v2.2.3, which comes with an elixir API client generator. Please give it a try and let us know if you’ve any feedback.
Here are some (but not all) companies using Swagger Codegen in production: GitHub - swagger-api/swagger-codegen: swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.
Disclosure: I’m a top contributor to Swagger Codegen
3 Likes
The Generated client uses Tesla HTTP client library. Generator is written in Java.
Another way is to use Swagger Codegen online generator via https://editor.swagger.io.
If you’ve any questions or feedback, please let us know via Sign in to GitHub · GitHub
2 Likes
UPDATE: myself and other top contributors (40+) have decided to fork Swagger Codegen to maintain a community-driven version called “OpenAPI Generator” (openapi-generator.tech), which supports both OpenAPI spec v2 and v3.
For the reasons behind the fork, please refer to the Q&A (github .com/OpenAPITools/openapi-generator/blob/master/docs/qna.md)
4 Likes
