Hey HN! We've developed OpenAPI AutoSpec, a tool for automatically generating OpenAPI specifications from localhost network traffic. It’s designed to simplify the creation of API documentation by just using your website or service, especially useful when you're pressed for time.<p>Documenting endpoints one by one sucks. This project originated from us needing it at our past jobs when building 3rd-party integrations.<p>It acts as a local server proxy that listens to your application’s HTTP traffic and automatically translates this into OpenAPI 3.0 specs, documenting endpoints, requests, and responses without much effort.<p>Installation is straightforward with NPM, and starting the server only requires a few command-line arguments to specify how and where you want your documentation generated ex. npx autospec --portTo PORT --portFrom PORT --filePath openapi.json<p>It's designed to work with any local website or application setup without extensive setup or interference with your existing code, making it flexible for different frameworks. We tried capturing network traffic on Chrome extension and it didn't help us catch the full picture of backend and frontend interactions.<p>We aim in future updates to introduce features like HTTPS and OpenAPI 3.1 specification support.<p>For more details and to get started, visit our GitHub page (<a href="https://github.com/Adawg4/openapi-autospec">https://github.com/Adawg4/openapi-autospec</a>). We also have a Discord community (<a href="https://discord.com/invite/CRnxg7uduH" rel="nofollow">https://discord.com/invite/CRnxg7uduH</a>) for support and discussions around using OpenAPI AutoSpec effectively.<p>We're excited to hear what you all think!
When you build an API, please start with the OpenAPI specification, before you write any code for your API.
It can be iterative, but for every part, just start with the OpenAPI, and think about what you want from the API, what do you want to send, and what to receive.<p>It is like the TDD approach, design before build.<p>Writing or generating tests after you build the code, is the same as this.
It is guessing what it should do.
The OpenAPI specification, and the tests should tell you what it should do, not the code.<p>If you have the specification, everyone (and also AI) can write the code for you to make it work.
But the specification is about what you think it should do.
That are the questions and requirements that you have about the system.
I’ve only glanced at the code on mobile, but am I reading this right? It seems like this does pretty much… nothing apart from writing everything to a .har file, and then calls out to a separate library called “har-to-openapi” to do the actual work?<a href="https://github.com/jonluca/har-to-openapi">https://github.com/jonluca/har-to-openapi</a>
A nice tool for research, or for documenting third-party APIs. Let's not forget, though, that one of the goals of OpenAPI is to serve as a design and documentation artifact in design-first API development; generating OpenAPI from code or, as in this case, from network traffic, is an interesting complement and something you can use to test the implementation against the design.
This is fantastic! I think I'll try to use this to generate the spec for openlibrary.org APIs. We have a few basic ones now but it's a huge pain to write. Someone looked into generating them from the python code but it didn't pan our.
I have a similar need but for the FHIR[1] spec, which has its own way of describing RESTful http endpoints that serve FHIR data.<p>I was looking into how this works for inspiration, and it seems like the work of inferring the OpenAPI definition from recorded requests/responses is handled by the har-to-openapi nodejs library [2]. Is this by the same team? If not, kudos for packaging this up in a proxy -- seems like a useful interface into that library.<p>1. <a href="https://www.hl7.org/fhir/" rel="nofollow">https://www.hl7.org/fhir/</a><p>2. <a href="https://github.com/jonluca/har-to-openapi">https://github.com/jonluca/har-to-openapi</a>
I thought I recalled something similar to this posted in the past.<p><a href="https://news.ycombinator.com/item?id=38012032">https://news.ycombinator.com/item?id=38012032</a><p>(5 months ago)
Another good option for this kind of thing is Optic: <a href="https://www.useoptic.com/docs/generate-openapi-from-tests" rel="nofollow">https://www.useoptic.com/docs/generate-openapi-from-tests</a>
I wrote a tool for work that does the same thing based on request logs. It would parse each line into a structure then merge the same call point structures down to one spec. It was helpful to see the api but in the end was not that helpful in back filling the openapi spec.<p>things to consider:
- junk data from users will show up. unless your downstream service rejects extra params users will mess with you.
- it documents each endpoint but its harder to say if this "user" data is the same as another's endpoints "user"
- it is hard to tell if users are hitting all endpoint inputs/outputs without manual review.
Is this comparable to Akita? <a href="https://www.akitasoftware.com/" rel="nofollow">https://www.akitasoftware.com/</a><p>> By watching API traffic live and automatically inferring endpoint structure, Akita bypasses the complexity of implementing and maintaining monitoring and observability.<p>> […]<p>> - Export your API description as an OpenAPI spec.<p>(Not affiliated, nor am I a user of either of these.)
This looks interesting - it seems like it wouldn't be a huge lift to turn this into something that compares against an existing spec too. create an AutoSpec, take your defined spec, and spot the difference.
Although this feels like a ok-ish approach to just serve API docs to users, you are missing the whole point of specs if you use this approach. I have started to extensively use spec-first approach with open API. You wouldn't believe how many hours it saved for me despite the initial cost of time to get things started. For example, No need to tediously write DTOs ever, just have them generated using API spec. Need an SDK for API consumers, just generate an SDK using the spec for almost all the popular languages. While using Open API as just an API documentation is fine, it is a waste of potential that Open API provides.
Reminds me of <a href="https://github.com/alufers/mitmproxy2swagger">https://github.com/alufers/mitmproxy2swagger</a> which I discovered from this thread <a href="https://news.ycombinator.com/item?id=31354130">https://news.ycombinator.com/item?id=31354130</a><p>I generated some specs from that!<p>I ran into trouble keeping them up to date.
This is probably cool and useful, but there's no way to know how much of the API you're covering, right?<p>I find that the real shortage of tools exists going the other way: from OpenAPI to code. The ecosystem has proven to be a huge disappointment there, comprising a janky collection of defective tools that still (years later) don't support version 3.1 (a critical update).