Converting Java Types to Swagger Types


Swagger Specification (aka OpenAPI Specification) is a way of defining and describing an RESTFul APIs. It provides means to compose components of an API, its endpoints, operations on those endpoints, return types of those operations in a plain text format into a single text file which is machine readable and can later be used to facilitate the auto generation of API stubs and to generate live API documentations. Live API documentation is one that is interactive and let users to make API invocations just within the documentation itself.

Swagger Specification file can be of type JSON, or YAML and follows the JSON standards.

Sample Structure of a Swagger File:

    {
        swagger : "2.0",s
        info : {..},
        host : "127.0.0.1:8081/openmrs/ws/rest",
        basePath : "/v1",
        tags : [..],
        consumes : [..],
        produces : [..],
        paths : {..},
        securityDefinitions : {..},
        definitions : {..}
    }

OpenAPI specification defines it’s own set of data types which definitely are different from the types of the language in which your API is written. So for example float and double will be represented there as the type number and date will be represented as the type string.

Say our Person resource have the attibute dateOfBirth, in the Swagger file it will be represented in the format:

dateOfBirth:
        type: string
        format: date 

If we’re to use swagger-core library and its annotations as the means of generating the swagger spec, it’d automatically take care of all the type conversions. But in case we’re generating the swagger spec programmatically by iterating over our API resource classes, then we’d need a way of converting the types of our programming language to their corresponding data types. As you might know the objective of my GSoC project is to improve OpenMRS Swagger Specification. However all the data types there are set to string which needs improvement. So I’ve been looking for the best means to map those properties into more appropriate data types which will require conversion of Java Types to Swagger Types.

I’d keep updating this post about my progress on improving OpenMRS Swagger Specification by use of better schema objects with the correct data types.

Activity Log:
* New talk thread: https://talk.openmrs.org/t/restws-562-talk-thread-adding-support-for-datatypes/11778
* Looking into RESTWS-562 Improve Resource Definition Documentation

Leave a comment

Your email address will not be published. Required fields are marked *