TE
科技回声
首页24小时热榜最新最佳问答展示工作
GitHubTwitter
首页

科技回声

基于 Next.js 构建的科技新闻平台,提供全球科技新闻和讨论内容。

GitHubTwitter

首页

首页最新最佳问答展示工作

资源链接

HackerNews API原版 HackerNewsNext.js

© 2025 科技回声. 版权所有。

Ask HN: How do you make sure a back end matches API-spec?

4 点作者 dachrillz将近 3 年前
Hello everyone,<p>I&#x27;ve sort of come to the conclusion that I prefer writing API-specification (Open API in this case) before starting to write the application itself.<p>The reason mainly being that if one writes the specification first, one has to think through the api, its error codes an so forth. There is nothing wrong with going the other way, namely generating the specification from the code. However, I have this intuition that there will always be edge cases where you will end up having to manually write parts of the specification anyways.<p>This means that there is a great risk that the specification drifts from the implementation as the application&#x2F;specification matures. The reason being is that one has to manually make sure that the specification matches the application, which is bound to be error prone!<p>My question is basically, how would you approach this problem? Do you know any tools that can help one make sure the specification matches the application? I&#x27;ve looked through some of the &quot;Open API tools&quot; [1], but none of them seem to really fully solve the problem.<p>Thank you for your time :D<p>[1] https:&#x2F;&#x2F;openapi.tools&#x2F;

2 条评论

yababa_y将近 3 年前
Great question! It fractally occurs at every level of the stack, I dealt with it when formally verifying operating systems, compilers, and runtimes: what do we mean by correct, and how can we assure our implementation has that property? You have the right instinct that it&#x27;s important to have a specification.<p>One approach is to use an &quot;executable specification&quot;, and now the problem becomes is the specification interpreter&#x2F;compiler correct? If so, your implementation has no choice but to match the specification. The Python library Connexion implements this approach. <a href="https:&#x2F;&#x2F;connexion.readthedocs.io&#x2F;en&#x2F;stable&#x2F;routing.html" rel="nofollow">https:&#x2F;&#x2F;connexion.readthedocs.io&#x2F;en&#x2F;stable&#x2F;routing.html</a> you augment your spec with specific python functions. It will automatically validate all requests against the spec.<p>Another approach is template generation, where the specification becomes input to a code generation, forming the skeleton that you fill out with your code. Swagger Codegen uses this approach. There are other generators too. I haven&#x27;t used them, but I&#x27;d be worried about the overhead of regeneration&#x2F;specification change, and possible implementation drift.<p>At a different level entirely, you have automated testing. <a href="https:&#x2F;&#x2F;dredd.org&#x2F;en&#x2F;latest&#x2F;index.html" rel="nofollow">https:&#x2F;&#x2F;dredd.org&#x2F;en&#x2F;latest&#x2F;index.html</a> is a great tool for OpenAPI. It&#x27;s basic behavioral testing that the implementation matches the spec. If you&#x27;re using the above approaches, running such a test is kinda superfluous. <a href="https:&#x2F;&#x2F;schemathesis.readthedocs.io&#x2F;en&#x2F;stable&#x2F;" rel="nofollow">https:&#x2F;&#x2F;schemathesis.readthedocs.io&#x2F;en&#x2F;stable&#x2F;</a> is another cool one. If your main worry is specification drift, these tools are your friends.
mdcds将近 3 年前
Several teams at my org use Smithy. The gist of it is that you define the spec and Smithy will generate the data model and clients.<p><a href="https:&#x2F;&#x2F;awslabs.github.io&#x2F;smithy&#x2F;" rel="nofollow">https:&#x2F;&#x2F;awslabs.github.io&#x2F;smithy&#x2F;</a>