Show HN: Auto-generate an OpenAPI spec by listening to localhost

178 点作者 adawg4大约 1 年前

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.Documenting endpoints one by one sucks. This project originated from us needing it at our past jobs when building 3rd-party integrations.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.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.jsonIt'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.We aim in future updates to introduce features like HTTPS and OpenAPI 3.1 specification support.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.We're excited to hear what you all think!

17 条评论

w3news大约 1 年前

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.It is like the TDD approach, design before build.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.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.

评论 #39821417 未加载

评论 #39821408 未加载

评论 #39823467 未加载

评论 #39821647 未加载

评论 #39822683 未加载

评论 #39821427 未加载

评论 #39823802 未加载

评论 #39825309 未加载

评论 #39823179 未加载

评论 #39821429 未加载

radicality大约 1 年前

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>

评论 #39833784 未加载

remoquete大约 1 年前

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.

评论 #39821395 未加载

spxneo大约 1 年前

I think pairing this tool with something that recursively clicks through app would be insanely helpful. (the latter is what I have trouble finding)

评论 #39820585 未加载

评论 #39820777 未加载

评论 #39819857 未加载

raybb大约 1 年前

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.

评论 #39831228 未加载

arscan大约 1 年前

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.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.1. <a href="https://www.hl7.org/fhir/" rel="nofollow">https://www.hl7.org/fhir/</a>2. <a href="https://github.com/jonluca/har-to-openapi">https://github.com/jonluca/har-to-openapi</a>

hnrodey大约 1 年前

I thought I recalled something similar to this posted in the past.<a href="https://news.ycombinator.com/item?id=38012032">https://news.ycombinator.com/item?id=38012032</a>(5 months ago)

评论 #39819815 未加载

rattray大约 1 年前

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>

sbeckeriv大约 1 年前

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.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.

评论 #39822479 未加载

tczMUFlmoNk大约 1 年前

Is this comparable to Akita? <a href="https://www.akitasoftware.com/" rel="nofollow">https://www.akitasoftware.com/</a>> By watching API traffic live and automatically inferring endpoint structure, Akita bypasses the complexity of implementing and maintaining monitoring and observability.> […]> - Export your API description as an OpenAPI spec.(Not affiliated, nor am I a user of either of these.)

beardedwalleye大约 1 年前

I could see this (or similar) being useful for generating a spec for an old, undocumented, legacy "service"

soneil大约 1 年前

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.

jzig大约 1 年前

Feature request: a browser extension that intercepts HTTP requests for any given website (instead of localhost) and documents their API :)

评论 #39822850 未加载

0cf8612b2e1e大约 1 年前

Could this work with previously saved traffic dumps?

评论 #39819641 未加载

dingi大约 1 年前

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.

nattaylor大约 1 年前

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>I generated some specs from that!I ran into trouble keeping them up to date.

评论 #39821272 未加载

评论 #39820347 未加载

DidYaWipe大约 1 年前

This is probably cool and useful, but there's no way to know how much of the API you're covering, right?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).

评论 #39821229 未加载

评论 #39820355 未加载