Sphinx - OpenAPI

を使うと Sphinx Docs に OpenAPI の仕様を表示できる。OpenAPI についてる browser (?) (Swagger Editor の右側のようなやつ) のように interactive ではないが、 static なので見やすく、印刷にも適していそう。

しかし API model に JSON ref ($ref と付いているもの) を使っていて、それが入れ子になっていると正しく parse してくれないっぽい。

を使って $ref を展開して別の JSON として保存して sphinx に食わせたららうまくいった。時間があったら pull req. 投げたい。

これだけではうまくいかなかった。 allOf の部分も merge したらできた

allOf とかは JSON Schema の仕様らしい

benedict を使ってこのようにした

code:python

from benedict import benedict

import jsonref

json_dict = jsonref.load(open(args.infile))

d = benedict(json_dict)

keypaths = d.keypaths()

print(allOfs)

def dic_merge(L):

d = {}

for l in L:

d.update(l)

return d

for allOf in allOfs:

schema = allOf.replace('.allOf', '')

print(schema)

dschema = dic_merge(dallOf)

PDF にするには sphinxdoc/sphinx-latexpdf が良いが、 design は simple.