Developers February 15, 2020

Anyone using OpenAPI (F.K.A. Swagger) specs?

Matt Hart @matt_h_

I've used OpenAPI frequently at past jobs for documenting my REST APIs and generating client code. I'm working on a tool in the OpenAPI ecosystem, but I'm starting to fear its not as widely used as I thought.

Any IndieHackers using OpenAPI? For what purpose? Have you found it valuable?

Happy Hacking

  1. 3

    I used it a lot at my last job. Our React/Node.js application was centered around providing mock implementations of corporate (non-public) APIs so developers could write and test their apps that use those APIs without having access to the corporate network where the real APIs were running. As a developer you would just run the node app on your development machine and configure your app to call the mock REST endpoints. Each mock API was implemented in a node module that could be installed into the core framework so any team of developers could add their APIs to the application. We defined all of the mock APIs in OpenAPI, used swagger-codegen to generate stub implementations, and I wrote some code that let you override the generated stubs by following a file-naming convention (e.g. if swagger-codegen created a file called FooBarService.js you could add FooBarServiceCustom.jsand export functions with the same name, and the application would call yours instead). We used swagger-ui to let users of the application read/learn about the API, and interact with the mock API implementations through the UI using the "try it now" feature. The tools work pretty well, but they lag behind the latest specs. I'm not sure how much they're actually being used.

    On my own app that I recently started working on, I'm keeping a swagger.yaml file up-to-date just so I have something for myself to remind me what I implemented without having to read through the code.

    1. 2

      Wow, thanks for the detailed writeup. It seems like you are pretty experienced with swagger.

      Would you find value in a tool that is essentially a more polished swagger-ui? Something that presents your API in a modern fully-interactive UI that you can customize?

      1. 1

        I am evaluating some tools for a very large org that deals with thousands of OpenAPI spec. We would like to standardize the rendering/viewing of these API specs that we will be exposing to our internal and external customers. Every department in the org have their own product branding and therefore the need of customization/security etc are needed

        I am not sure how we are going to consume the service that is outside of my job-function but if it helps then I know that we have the option of hosting this tool on our own private cloud which frees up many liability issues, but incase you are providing it as a SASS then you should be able to show us an uptime record for last 18 months and various security audits

        We are currently evaluating

        • Swagger UI / Swagger Hub
        • Redoc
        • Spotlight
        • RapiDoc

        so far RapiDoc (https://mrin9.github.io/RapiDoc) beats all of them. Do you have a demo site for people to evaluate like all these above mentioned tool offers ?

      2. 1

        Swagger-ui works pretty well, is dependency free, and can be customized. If the tool looked a lot better or was easier to customize then maybe. Personally I'm not doing much with OpenAPI anymore, but back when I was at my last job I would have been interested in anything that was an improvement.

  2. 2

    We use it for our product and we rely on it a lot!
    The workflow we follow might be interesting to someone so sharing here.

    1. We have complete rest api divided into Admin, B2B, B2C, SDK and Common files.
    2. We customised swagger codegen to generate the code by fetching the open spec from the files above
    3. Our code for both backend(60%) and frontend SDK(100%) is totally generated.

    For the backend, from the code-generator we generate the required boilerplate code and we need to only implement the service code alone, which is mainly the business logic. Routing, Controllers, Versioning, DTO's, Schema validation(through ajv) per request, etc "all" created on the fly from the code generator. AJV takes the schema of the spec and validates for every request directly :)

    When ever we need to modify any attribute or add any in the spec, we run the code generation scripts and we get informed about missing things by compilation errors after code is generated. Thanks to TypeScript, else it won't be that easy with a non-strictly typed language like JS :)

  3. 1

    OpenAPI is far more used than one may think. Most apps have a restful API now, most teams now know the importance of documentation.

    I use it at work, I also use it for personal projects. I have a boilerplate for node.js webapp, it integrates OpenAPI and I nearly always start from there.

    1. 2

      With my project (https://spireui.com), I'm trying to build a tool that generates a web app from your OpenAPI spec. Do you think that's something you would find useful?

      And thanks for your input! At this early stage, any feedback from OpenAPI experts is extremely valuable.

  4. 1

    I've used swagger/open-api a lot for work projects. If I started any of those today, I'd be far more likely to start with GraphQL because I cannot think of a single API instance where we didn't have to go back and update/modify/extend/add-to the API. I feel pretty safe in saying that the changes are constant and on-going.

    The single instance of GraphQL (brand new, just got it up) has already been able to handle several requests that we did not previously think of and that would have required several changes using our previous practices.

  5. 1

    I'm biased but..look at GraphQL. It has static typing built-in and it's self-documenting through its introspection interface. OpenAPI was never that popular, GraphQL, on the other hand, is growing quickly and already quite popular.

  6. 1

    I have been using it back in the day in my quest to figure out how I could work as efficiently as possible. Back in the day the problem was integration between API and documentation. It just didn't fit as good as I would have wanted it to. These integration issues have led me to abandon the technology.

    Now I use GraphQL, and I couldn't be more happier. It includes metadata, which enables several incredibly powerful programming paradigms, and integrates well for me.

  7. 1

    I use https://github.com/zalando/connexion for python based APIs. It takes the OpenAPI spec and creates the necessary setup for flask in run time. i just have to write the actual function which implements the logic of the API.

  8. 1

    I use openAPI to document my APIs with the help of Swashbuckle (https://github.com/domaindrivendev/Swashbuckle.AspNetCore) for asp.net core. It takes your controller signatures and automatically generates swagger definitions

Recommended Posts