https://github.com/SmartBear/swagger4j

A simple java library for reading and writing swagger definitions
https://github.com/SmartBear/swagger4j

Last synced: 3 days ago
JSON representation

A simple java library for reading and writing swagger definitions

• Host: GitHub
• URL: https://github.com/SmartBear/swagger4j
• Owner: SmartBear
• Archived: true
• Created: 2013-05-25T23:32:28.000Z (over 11 years ago)
• Default Branch: master
• Last Pushed: 2020-10-15T19:26:40.000Z (about 4 years ago)
• Last Synced: 2024-08-03T23:24:32.064Z (3 months ago)
• Language: Java
• Size: 134 KB
• Stars: 26
• Watchers: 40
• Forks: 13
• Open Issues: 8
• Metadata Files:
  • Readme: README.md
  • License: LICENSE-2.0.txt

Awesome Lists containing this project

README

        
## swagger4j

A simple java library for reading and writing [Swagger 1.X definitions](https://swagger.io). Supports both JSON and XML formats. The current version is

reasonably in line with the latest swagger core release except that it doesn't support any of the JSON Schema/Data Model constructs yet. Apache 2.0 licensed.

If you're interested in reading Swagger 2.0 definitions you're better off using the official [swagger-parser](https://github.com/swagger-api/swagger-parser)

### Getting started

Clone this repo from GitHub and build it yourself with maven (with "mvn install"). 

The latest version is also available in the SmartBear maven repository at soapui.org, add this to your pom with

```xml

    

        soapUI Repository

        http://www.soapui.org/repository/maven2

    

```

and add the corresponding dependency:

```xml

    com.smartbear

    swagger4j

    1.0.0

```

swagger4j has a runtime dependency

on jsonp ([https://java.net/projects/jsonp/](https://java.net/projects/jsonp/)) which you can add to your maven pom with.

```xml

    org.glassfish

    javax.json

    1.0-b06

```

Once added to your classpath you can start reading swagger definitions, for example

```java

ResourceListing resourceListing = Swagger.readSwagger( "http://petstore.swagger.wordnik.com/api/api-docs.json" )

for( ResourceListingApi apiRef : resourceListing.getApis() )

{

   ApiDeclaration apiDeclaration = apiRef.getDeclaration();

   for( Api api : apiDeclaration.getApis())

   {

       ...

   }

}

```

and of course you can write them as well

```java

SwaggerFactory factory = Swagger.createSwaggerFactory();

ApiDeclaration apiDeclaration = factory.createApiDeclaration( "http://api.mycompany.com/apis", "/user" );

Api api = apiDeclaration.addApi( "{id}" );

Operation op = api.addOperation( "getuserbyid", Operation.Method.GET );

op.addParameter( "id", Parameter.ParamType.path );

ResourceListing rl = factory.createResourceListing( "http://api.mycompany.com/apis" );

rl.setApiVersion( "1.0" );

rl.addApi( apiDeclaration, "user-doc.{format}" );

Swagger.writerSwagger( rl, "api-docs" );

```

The API is closely modeled after the Swagger specification, if you are familiar with that it should be a breeze to use.

If you aren't familiar with Swagger and its spec head right over to the swagger website at 

[https://github.com/wordnik/swagger-core/wiki](https://github.com/wordnik/swagger-core/wiki) to learn all about it.

Javadoc is available in the zip at sourceforge.

### Library Design

Swagger4j uses a standard Factory/Builder approach with interfaces defining the entire Swagger object model and a

default implementation implementing them. If you have any suggestions on how to improve the actual API please don't

hesitate to get in touch by adding tickets here at GitHub for bugs, issues, feature requests - Thank you!

Please note the following:

- the whole DataModel/DataType part of Swagger is not yet supported

- paths to APIs referred to in a ResourceListing are resolved by adding the path of the api to the basePath defined

in the resourceListing. If the basePath is relative - it is resolved relatively to the host/root of the ResourceListing

URI.

### Usages

* Version 0.2+ of the SoapUI-Swagger-Plugin use swagger4j to parse and generate Swagger definitions.

### Future improvements

* None planned at this point!

### Release History

* 20130527 - Initial beta1 release

* 20131119 - beta2 release, adds support for Swagger 1.2 and 1.0

* 20140505 - beta3 bugfixes

* 20140512 - beta4 more bugfixes

* 20151029 - 1.0.0 release - more bugfixes