Show HN: Auto-generate an OpenAPI spec by listening to localhost (opens in new tab)

I get the feeling you may not have gone 0-1 on an API before. In general, you have 1 consumer when you're starting off, and if you're lucky your API gathers more consumers over time.

In that initial implementation period, it's more time-consuming to have to update a spec nobody uses. Maintaining specs separately from your actual code is also a great way to get into situations where your map != your territory.

I'd instead ask: support and use API frameworks that allow you to automatically generate OpenAPI specs, or make a lot of noise to get frameworks that don't support generating specs to support that feature. Don't try to maintain OpenAPI specs without automation :)

I don't want to write OpenApi. Yaml is a terrible programming language, and keeping it in sync with actual code is always a nightmare.

I've been using a tool to generate OpenApi from code, and am pretty happy with that workflow. Even if writing the API before logic, I'd much rather write the types and endpoints in a real programming language, and just have a `todo` in the body.

You can still write API-driven code without literally writing OpenApi first.

100% agree with you... taking the time to do/go design first greatly improves the quality of the final API...

But as some comments below point out, an OpenAPI spec is a pain to create manually which is why TypeSpec from Microsoft is such a great tool. Lets you focus on the important bits of creating a solid API (model, consistency, best practices) in an easy to use DSL that spits out a fully documented OpenAPI spec to build against! see https://typespec.io/

What’s wrong with designing an API by writing its code? Code itself is a design tool (and usually any decent programming language is a better design tool than YAML)

Unfortunately OpenAPI specs suck to write manually.

Generating OpenAPI spec from the server code has always felt significantly better for me.

I completely agree as a general design principle, but I still think there’s a place for the above tool.

Example: I used to work at a place that had a massive PHP monolith, developed by hundreds of devs over the course of a decade, and it was the worst pile of hacky spaghetti code I’ve ever seen. Unsurprisingly, it had no API spec. We were later doing tonnes of work to clean it up, which included plans to add an API spec, and switch to a spec-first design process (which we were already doing in services split from the monolith), but there was a massive existing surface area to spec out first. A tool like this would’ve been useful to get a first draft of the API spec up and running quickly for this huge legacy backend.

The API library I wrote for my last couple projects required the developer to fill in the openapi spec specifics and said spec was the part of the API itself, making it difficult to add something to the API that wasn't also in the spec.

Incoming request params, became validated and casted object properties. Outgoing response params were validated and casted according to spec.

In the end I think it worked really well, and loved not needing to maintain the spec separately. The annoying bit was adjusting the library when the spec changed.

And some gnarly bits of the spec that weren't easy to implement logically.

At any rate, it also made for a similar experience of considering the client experience while writing/maintaining the api.

I prefer going the other direction in practice, autogenerating the spec from the code e.g. with drf-spectacular for Django.

Waste of time imo if you use a framework like fastapi which generates the spec for you

As a curiosity, how do you feel about languages/frameworks where APIs can be pretty self-documenting? For example, Java/JAX-RS creates pretty self-documenting APIs:

    @Path("/people")
    public class PeopleApi {
        @Path("{personId}")
        @GET
        public Person getPerson(@PathParam("personId") int personId) {
            return db.getPerson(personId);
        }
    }

It's easy to generate a spec for a JAX-RS class because it has the paths, parameters, types, etc. right there. There's a GET at /people/{personId} which returns a Person and takes a path parameter personId which is an integer.

If we're talking about a Go handler which doesn't have that information easily accessible, I understand wanting to start with a spec:

    func GetPerson(w http.ResponseWriter, r *http.Request) {
        personId, _ := strconv.Atoi(r.URL.Path.something)
        person := db.GetPerson(personId)
        w.Write(json.marshal(person))
    }

    func GetPerson(c echo.Context) error { //or with something like Echo/Gin
        id := c.Param("id")
        person := db.GetPerson(id)
        return c.Json(http.StatusOK, person)
    }

In Go's case, there's nothing which can tell me what the method takes as input without being able to reason about the whole method. With JAX-RS, it's easy reflect on the method signature and see what it takes as input and what it gives back, but that's not available with Go (with the Go tools that most people are using).

This isn't meant as a Go/Java debate, but more a question of whether some languages/frameworks basically already give you the spec you need to the point where you can easily generate an OpenAPI spec from the method definition. Part of that is that the language has types and part of it is the way JAX-RS does things such that things you're grabbing from the request become method parameters before the method is called rather than the method just taking a request object.

JAX-RS makes you define what you want to send and what you want to receive in the method signature. I totally agree that people should start with thinking about what they want from an API, what to send, and what to receive. But is starting with OpenAPI something that would be making up for languages/frameworks that don't do development in that way naturally?

----------

Just to show I'm not picking on Go, I'm pretty sure one could create a Go framework more like this, I just haven't seen it:

    type GetPersonRequest struct {
        Request `path:/people/{personId}`
        PersonId int `param:path`
    }
    func GetPerson(personRequest GetPersonRequest) Person {
        return db.GetPerson(personRequest.PersonId)
    }

I think you'd have to have the request object because Go can annotate struct fields (with struct tags), but can't annotate method parameters or functions (but I could be wrong). The point is that most languages/frameworks don't have the spec information in the code in an easy way to reflect on like JAX-RS, ASP.NET APIs, and some others do.

1. What else should it do?

2. I think I like this blunt elevator pitch much better than OP's multiple paragraphs of text...

It makes sense, and we love API-first companies. How are frameworks prioritizing this? Seen DRF and lite star but seemed like this was needed to help at places we worked/API market reports about companies that hadn't put those standards in yet

One slightly related thing you can do is to test the API with schemathesis[0]

[0] https://github.com/schemathesis/schemathesis

This seems pretty simple to me to do. Search the html of the main page for anchor tags. Add the links in those tags to an array as your exploration frontier. Once done parsing that html, load the next link. Add deduplication to avoid loops and just run a depth-first search. What am I missing?

Open to ideas! We're thinking of adding agents/crawler suggestions to the github if there's a package that clicks around in that fashion

That would be awesome!

Love what Andrew is doing! We built this for localhost when testing vs. the client side with a Chrome extension.

Doesn't look like this tool is intended to be deployed into production where "junk data from users" would be encountered. My impression is it's a localhost proxy which only ever sees deliberate test traffic from the developer who's running it on their own machine.

(Although I'd be curious to see something very similar to this running in prod and generating WAF rules and/or alerting on suspicious requests. Kinda like Dynatrace or Splunk, but much more aware of the API documentation and expectations.)

See https://github.com/AndrewWalsh/openapi-devtools

Just replay into nc?

Super curious - How did you try keeping them up to date?

I think going from code to OpenAPI makes a lot more sense, at least for strong typed languages. And even if not directly translated from code, at least closer to the actual code, in annotations or something. Generating the spec from code removes a step, where you simply need to update code, rather than update the spec then update the code