良いOpenAPI Documentについて考えている

今週は「良い」OpenAPI Documentについて考えている。

「良い」というのはどういうことなのかが分かっていない。

例えば細野ら*1はOpenAPI Documentとその実装にずれがあることをあげている。

本来的には仕様書であるOpenAPI Documentと実装がずれているのであれば、実装誤りのはずですが、現実的には実装が正でOpenAPI Documentの定義が誤りということが多いように思う。

つまりこのような状態にあるOpenAPI Documentとは「良く無い」OpenAPI Documentなのだろうと思う。 悪い理由は言いやすいけど、逆に良いOpenAPI Documentととなると悩む。

教授のアドバイスもあり古い論文に目を通そうとBoehmの「Verifying and Validating Software Requirements and Design Specifications」*2を読んでる。

タイトルの時点でVerificationとValidationの違いは難しいなと。

Boehmは「IEEE Standard Glossary of Software Engineering Terminology」の定義を引用しつつ以下のような質問で定義している。

• Verification. "Am I building the product right?"
• Validation. "Am I building the right product?"

そう考えると良い仕様書はcorrectな仕様書で、良い仕様書かをVerificationによって確認できるんだろうか。

*1:M. Hosono, H. Washizaki, Y. Fukazawa, and K. Honda, “An Empirical Study on the Reliability of the Web API Document,” in 2018 25th Asia-Pacific Software Engineering Conference (APSEC), 2018, pp. 715–716.

*2:[1] B. W. Boehm, “Verifying and Validating Software Requirements and Design Specifications,” IEEE Software, vol. 1, no. 1, pp. 75–88, Jan. 1984.