Orthanc Swagger Schema

Hi All,

I’ve been working with swagger/openapi quite alot lately. I saw that creating one for Orthanc is on the roadmap. I ran through the Orthanc REST API docs and made a spec document for it if anyone is interested. I have attached it to the is post. It can be loaded fairly easily into the swagger editor (https://editor.swagger.io/) and hosted using the swagger UI tool on a website.

I think it covers everything in the Orthanc Book for the REST API. Some details are missing because the pages didn’t give examples of some of the response bodies for example. It may be possible to define re-usable schema types for the response and request bodies and some of the low-level data types. There’s a bit of duplication at the moment because I’m not entirely sure which types are in fact the same in the Orthanc code. I tried organizing requests into sections that somewhat resemble the sections in the documentation while trying to keep similar URL paths together. Hopefully, it flows from simpler endpoints near the beginning to the more complex and advanced ones at the bottom.

I noticed that the asynchronous mode is documented saying that the bulk store “/modalities/…/store” supports it and that you just add the “Synchronous”: false flag to the POST request body. But, it seems that the POST request body is a JSON array. I’m not quite sure what’s the correct form there. I could give it a try sometime and figure it out, but I thought I would point out the ambiguity in the documentation. The same is true of the orthanc peer store equivalent.

Cheers,
Chris

orthanc-openapi.yaml (67 KB)

Hello,

Many thanks for this great, extremely useful, contribution!

We’ll be thinking about how to best take advantage of this documentation. I’m considering the following:

  1. Put the source code (in the OpenAPI) format within the dedicated repository: https://bitbucket.org/sjodogne/orthanc-book
  2. Split your file in different sections (if possible) to allow for easier modifications of the various areas of the REST API
  3. Automatically run Swagger on the repository above to continuously regenerate the documentation by our CIS and publish it onto, say, http://api.orthanc-server.com/

Can we consider that you agree to release this documentation using the CC-BY-SA 4.0 that is used for the Orthanc Book?

Obviously, it would be extremely interesting for future work to include the material from the integration tests that have a much larger covering of the REST API than the text of the Orthanc Book:
https://bitbucket.org/sjodogne/orthanc-tests/src/default/Tests/Tests.py

Kind Regards,
Sébastien-

Hi Sébastien,

Thanks for the suggestions.

We’ll be thinking about how to best take advantage of this documentation. I’m considering the following:

  1. Put the source code (in the OpenAPI) format within the dedicated repository: https://bitbucket.org/sjodogne/orthanc-book

Sure, I can look into creating the bitbucket equivalent of a pull request for review.

  1. Split your file in different sections (if possible) to allow for easier modifications of the various areas of the REST API

The file is currently organized for the most part into sections (ie. tags) that are generally kept together within the file. Would you like to see them split into separate files? I think that it is possible to do that. Would you like to see a different structure to the sections?

  1. Automatically run Swagger on the repository above to continuously regenerate the documentation by our CIS and publish it onto, say, http://api.orthanc-server.com/

I have recently set up a hosted docker container for my company for our own REST API’s with the official Swagger UI container provided on dockerhub. If this docker container is sufficient to host this API site I can provide some guidance on how to do that. Alternatively, there are website generators for swagger, but I don’t have experience with them.

Can we consider that you agree to release this documentation using the CC-BY-SA 4.0 that is used for the Orthanc Book?

Yes, I have authorization to make this contribution to the project under whatever license is preferred.

Obviously, it would be extremely interesting for future work to include the material from the integration tests that have a much larger covering of the REST API than the text of the Orthanc Book:
https://bitbucket.org/sjodogne/orthanc-tests/src/default/Tests/Tests.py

Ah, I can have a look there and try to fill in any gaps or incorrect assumptions in the spec.

Thanks,
Chris

Hi,

Thanks for your feedback!

I have just managed to setup an online version of your OpenAPI:
https://api.orthanc-server.com/

This API is automatically re-generated by the CIS of Orthanc, by running ReDoc on the following file (for the moment, it corresponds exactly to your original submission):
https://bitbucket.org/sjodogne/orthanc-book/src/default/OpenAPI/orthanc-openapi.yaml

Pull requests are obviously warmly welcome to improve the documentation!

It would be interesting to merge the following previous attempt of documentation (caution that the BSD-3 clause used in this repo is a priori not suitable for a documentation using CC-BY-SA):
https://github.com/bastula/swagger-orthanc/

I let the contributors decide whether the large file should be split into smaller files.

Cheers,
Sébastien-

Hi Sébastien,

If I need to relicense my repo, it is no issue to do that. Please let me know.

I am glad someone is picking up the torch to do swagger/openapi as it is immensely valuable.

Thanks,

Aditya

Hi,

I have reviewed the Tests.py file and learned a whole lot more about the Orthanc REST API capabilities. :slight_smile:

Also, I checked Aditya’s GitHub repo and I believe I have covered what was already there and in the new OpenApi v3 format.

Here’s an enhanced version of the schema attached to this post. I will look at creating a BitBucket/hg patch request if that’s preferred.

I know that it’s still missing areas such as media, archive, protected, orthanc metadata, attachments, all the tools, shared tags, modules, XML content types and instance reconstruction. If I have time, I can take a look at those. Alternatively, I could raise an issue to track these.

Cheers,
Chris

orthanc-openapi-2.yaml (81.5 KB)

Dear Aditya and Chris,

Thanks again for your great contributions!

I have integrated the last version of Chris’ into the repository. For further improvements, you should now make pull requests on our official repository for documentation, as explained in the “REST API of Orthanc” section at this location:
https://bitbucket.org/sjodogne/orthanc-book/src/default/

The repository uses Mercurial, but this is as simple to use as git:
https://madradavid.com/mercurial-git-users/

As suggested by Chris, I have also opened an issue tracker that is dedicated to the documentation of Orthanc:
https://bitbucket.org/sjodogne/orthanc-book/issues?status=new&status=open

Kind Regards,
Sébastien-