0

We have a system that uses http POST with JSON as an RPC method. It is an in house solution for internal components communication.

The requests and responses are described each by a Java bean (POJO).

My question is, how can I use swagger annotations to create nice documentation in the swagger standard?

I am not afraid from messing around with existing code, but I was wondering if anyone has some experience with something similar.

The goal is to use Swagger UI to display nice docs and give a playground for users to invoke the Apis.

Improve this question
4
  • RPC is a bit generic. What transfer protocol do you use? How do you (technically) expose your API? Commented Jan 14, 2015 at 17:35
  • We use a dispatcher servlet that takes JSON as input and return JSON output. Commented Jan 14, 2015 at 17:37
  • 1
    So a single endpoint accepting numerous types of JSON inputs, and for each input produces a different possible JSON output? Not a separate endpoint (URL) for each operation type? Commented Jan 14, 2015 at 17:40
  • Yes. The JSON payload also describes the type of the request. Commented Jan 14, 2015 at 17:41

2 Answers 2

Reset to default
1

Based on the comments above, it's impossible to describe this sort of API using Swagger. The Swagger specification is intended to REST-based APIs, where the URLs serve as a unique endpoints to describe an operation, and not the payloads.

By definition, Swagger considers a unique operation to be the combination of a URL and the HTTP method (there are requests to expand the definition to include the mime type as well, for example, but it is not currently available).

There is simply no way to describe a single endpoint that operates multiple requests types, each having its own output.

There may be a solution for what you request in the future, but it is not in the near future, not will it answer your requirements to the fullest.

To be clear - this is not an issue of messing around with code or anything. The specification itself doesn't support it.

Improve this answer
Sign up to request clarification or add additional context in comments.

3 Comments

What if I'll add a path param for each request type? That way I'll have a unique end point for each API method. Will there be a way to fulfill the requirement?
It will, as long as each endpoint allows for a single input and a single output, and if the input is a JSON, it is sent as the HTTP request payload. If you create a separate servlet for each endpoint, you could easily integrate swagger-core into it to produce the documentation.
theres a way to make this work, see my submitted answer
1

There are 2 simple tweaks required to make a swagger file work for any generic hand-built RPC application.

The first tweak is to make the swagger endpoints appear to be unique. This is done by defining each endpoint with a unique name after a hash in the context. This works because your app will not process the url past the '#' and this allows swagger to consider the path to be "unique". In reality though this technique will allow every unique path defined in the swagger file to actually invoke the same endpoint.


  paths:
    /endpoint#myUniqueCommandA
      ...
    /endpoint#myUniqueCommandB
      ...

The other tweak is needed to ensure the generated swagger clients will actually call the correct operation inside your RPC app. This is done by implementing a "defaulted single value" enum in each command's request object. The defined enum represents the corresponding attribute / value combo the api needs to pass to get dispatched to the right target action inside your application:


...
    definitions:
      MyUniqueCommandARequest: 
        type: object
        properties: 
          rest_call: 
            type: string
            enum: 
            - myUniqueCommandA
            default: myUniqueCommandA
   ...

      MyUniqueCommandBRequest: 
        type: object
        properties:
          rest_call:
            type: string
            enum: 
            - myUniqueCommandB
            default: myUniqueCommandB
   ...

In the above example, the property "rest_call" is what my underlying system uses to dispatch the request to the right underlying operation. The request object for myUniqueCommandA has its rest_call attribute defined as enum["myUniqueCommandA"]. The request object for myUniqueCommandB has its rest_call attribute defined as enum["myUniqueCommandB"].
Since these are defined as a single value enums that are also defaulted to that same value, the generated swagger classes that calls these apis will be wired to pass their correct routing value automatically.

Improve this answer

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.