openapi

[martijnlammers]

I'm currently trying to document my API, but I'm struggling to figure out how exactly the openapi section in 'app.json' is being used. I do comprehend the schema/notation that needs to be followed, however I'm unable to grasp how it integrates with swagger and how I can access the generated openapi document? Could I please get some elaboration on how it needs to be exercised?

[eddyashton]

There's an automatically generated endpoint /app/api, which returns an OpenAPI description of every endpoint under /app, and inserts the OpenAPI elements from app.json in the relevant place.

For instance with the tests/js-authentication app, which has empty openapi objects in its app.json, this endpoint just reports the HTTP methods available on each path but has no more information:

# This app has no OpenAPI information
$ cat ../tests/js-authentication/app.json
...
    "/secret": {
      "get": {
        ...
        "openapi": {}
      },
      "post": {
        ...
        "openapi": {}
      }
    },
    "/roles": {
      "post": {
        ...
        "openapi": {}
      }
    }
...

# Start up a test service running this app
$ ../tests/sandbox/sandbox.sh -p libjs_generic --js-app-bundle ../tests/js-authentication/

# Call the /app/api endpoint to read the generated OpenAPI document
$ curl https://127.0.0.1:8000/app/api -k | jq .
...
    "/roles": {
      "post": {}
    },
    "/secret": {
      "get": {},
      "post": {}
    },
...

Whereas in tests/js-app-bundle, which does have "openapi" elements, they're inserted in the correct place:

# This app has OpenAPI information
$ cat ../tests/js-app-bundle/app.json
...
    "/compute": {
      "post": {
      ...
      "openapi": {
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "op": {
                      "type": "string",
                      "enum": ["add", "sub", "mul"]
                    }
                    ...
          "responses": {
            "200": {
              "description": "Compute result"
              ...
...

# Start up a test service running this app
$ ../tests/sandbox/sandbox.sh -p libjs_generic --js-app-bundle ../tests/js-app-bundle/

# Call the /app/api endpoint to read the generated OpenAPI document
$ curl https://127.0.0.1:8000/app/api -k | jq .
...
    "/compute": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "left": {
                    "type": "number"
                  },
                  "op": {
                    "enum": [
                      "add",
                      "sub",
                      "mul"
                    ],
                    "type": "string"
                  },
                  ...
        "responses": {
          "200": {
            ...
            "description": "Compute result"
          }
...

(Hope this is still readable despite all the ... snips, just trying to point out the interesting bits of a large object)

Note that these OpenAPI documents describe everything under /app, including the built-in endpoints like /app/tx, /app/commit etc. We check in the current OpenAPI documents for the /gov and /node endpoints, and the /app endpoints of the logging sample app, under the schemas folder.

[martijnlammers]

It's still very readable yes. This did answer what I was looking for.

Sincere thanks for all the assistance you've granted me throughout the last couple weeks. It really helped me out a lot. Hope I wasn't taking too much of your time asking questions. : )

[eddyashton]

@mAlyanak No problem at all, happy to help! And answering these kinds of questions is a great way of improving our documentation for all new users - both providing a sort of FAQ here, and highlighting where we could be clearer in the main docs, so not taking too much time at all :)