Swagger 2.0 vs OpenAPI 3.0, conversion

https://swagger.io/docs/specification/2-0/basic-structure/ Swagger 2.0 specifications

https://swagger.io/docs/specification/basic-structure/ OpenAPI 3.0 specifications

https://editor.swagger.io/ Swagger Editor, it contains a menu to translate 2.0 into 3.0, but this works by sending the yaml to a remote conversion service, so it might not work in your premises. You can also install the container with swagger-editor https://hub.docker.com/r/swaggerapi/swagger-editor/ , but make sure that external connectoins are legal in your company.

Swagger for Java EE reasteasy or jersey

Making Swagger work in Spring is very easy.

You can use it also in Java EE (Wildfly, WebLogic, even Tomcat!!! )

but all the documentation I have found is a bit outdated:

I have tried APIEE https://dzone.com/articles/apiee-an-easy-way-to-get-swagger-on-java-ee and https://github.com/phillip-kruger/apiee but it's not showing my services and I see no error.

Some other outdated articles:

https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-2.X-Project-Setup-1.5



https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-RESTEasy-2.X-Project-Setup-1.5

I have no time now, but if I need to write REST services in Java EE I would not live without Swagger...

Swagger getting started

At first I tried to go to http://editor.swagger.io/ , generate the Maven project to generate a RestEasy-EAP server, build and deploy to Wildfly 12.

There I got this error:


ERROR [org.jboss.as.controller.management-operation] (Controller Boot Thread) WFLYCTL0013: Operation ("deploy") failed - address: ([("deployment" => "swagger-jaxrs-resteasy-eap-server-1.0.0.war")]) - failure description: {
"WFLYCTL0412: Required services that are not installed:" => [
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"org.jboss.resteasy.plugins.server.servlet.Filter30Dispatcher\".START",
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"javax.faces.webapp.FacetTag\".START",
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"org.jboss.resteasy.plugins.server.servlet.HttpServlet30Dispatcher\".START",
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".jndiDependencyService",
"jboss.naming.context.java.module.\"swagger-jaxrs-resteasy-eap-server-1.0.0\".\"swagger-jaxrs-resteasy-eap-server-1.0.0\".DefaultDataSource",
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"javax.servlet.jsp.jstl.tlv.ScriptFreeTLV\".START",
"jboss.undertow.deployment.default-server.default-host./v2",
"jboss.naming.context.java.jboss.datasources.ExampleDS",
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"com.sun.faces.config.ConfigureListener\".START",
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"javax.servlet.jsp.jstl.tlv.PermittedTaglibsTLV\".START"
],
"WFLYCTL0180: Services with missing/unavailable dependencies" => [
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"org.jboss.resteasy.plugins.server.servlet.HttpServlet30Dispatcher\".START is missing [jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".jndiDependencyService]",
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"javax.servlet.jsp.jstl.tlv.ScriptFreeTLV\".START is missing [jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".jndiDependencyService]",
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"javax.faces.webapp.FacetTag\".START is missing [jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".jndiDependencyService]",
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".jndiDependencyService is missing [jboss.naming.context.java.module.\"swagger-jaxrs-resteasy-eap-server-1.0.0\".\"swagger-jaxrs-resteasy-eap-server-1.0.0\".DefaultDataSource]",
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"org.jboss.resteasy.plugins.server.servlet.Filter30Dispatcher\".START is missing [jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".jndiDependencyService]",
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"javax.servlet.jsp.jstl.tlv.PermittedTaglibsTLV\".START is missing [jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".jndiDependencyService]",
"jboss.undertow.deployment.default-server.default-host./v2 is missing [jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"com.sun.faces.config.ConfigureListener\".START, jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"org.jboss.resteasy.plugins.server.servlet.Filter30Dispatcher\".START, jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"javax.servlet.jsp.jstl.tlv.ScriptFreeTLV\".START, jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"javax.faces.webapp.FacetTag\".START, jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"javax.servlet.jsp.jstl.tlv.PermittedTaglibsTLV\".START, jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"org.jboss.resteasy.plugins.server.servlet.HttpServlet30Dispatcher\".START]",
"jboss.naming.context.java.module.\"swagger-jaxrs-resteasy-eap-server-1.0.0\".\"swagger-jaxrs-resteasy-eap-server-1.0.0\".DefaultDataSource is missing [jboss.naming.context.java.jboss.datasources.ExampleDS]",
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"com.sun.faces.config.ConfigureListener\".START is missing [jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".jndiDependencyService]",
"jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".deploymentCompleteService is missing [jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"com.sun.faces.config.ConfigureListener\".START, jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"org.jboss.resteasy.plugins.server.servlet.Filter30Dispatcher\".START, jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"javax.servlet.jsp.jstl.tlv.ScriptFreeTLV\".START, jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"javax.faces.webapp.FacetTag\".START, jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"javax.servlet.jsp.jstl.tlv.PermittedTaglibsTLV\".START, jboss.undertow.deployment.default-server.default-host./v2, jboss.deployment.unit.\"swagger-jaxrs-resteasy-eap-server-1.0.0.war\".component.\"org.jboss.resteasy.plugins.server.servlet.HttpServlet30Dispatcher\".START]"
]
}



and the deployment fails. I felt discouraged and I turned to something simpler.

First I will implement my own Rest Service:

https://spring.io/guides/gs/rest-service/

then I run as http://localhost:8080/greeting

Then I move to adding Swagger to this REST webapp https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api.
I add the SwaggerConfig class with the @EnableSwagger2

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {                                    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                           
    }
}

Here I see something comforting


s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/greeting]}" onto public org.springframework.gsrestservice.Greeting org.springframework.gsrestservice.GreetingController.greeting(java.lang.String)
s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/swagger-resources/configuration/ui]}" onto public org.springframework.http.ResponseEntity<springfox.documentation.swagger.web.UiConfiguration> springfox.documentation.swagger.web.ApiResourceController.uiConfiguration()
s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/swagger-resources]}" onto public org.springframework.http.ResponseEntity<java.util.List<springfox.documentation.swagger.web.SwaggerResource>> springfox.documentation.swagger.web.ApiResourceController.swaggerResources()
s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/swagger-resources/configuration/security]}" onto public org.springframework.http.ResponseEntity<springfox.documentation.swagger.web.SecurityConfiguration> springfox.documentation.swagger.web.ApiResourceController.securityConfiguration()
pertySourcedRequestMappingHandlerMapping : Mapped URL path [/v2/api-docs] onto method [public


so now the endpoints are:

http://localhost:8080/greeting

http://localhost:8080/swagger-resources/configuration/ui

http://localhost:8080/swagger-resources/

http://localhost:8080/swagger-resources/configuration/security

http://localhost:8080/v2/api-docs


Then I add the io.springfox:springfox-swagger-ui:2.9.2 dependency

and I get the Swagger-UI at http://localhost:8080/swagger-ui.html

My code is available here https://github.com/vernetto/springbootrestswagger

The Baeldung code is here https://github.com/eugenp/tutorials/tree/master/spring-security-rest

Swagger Editor and generation of a Java API for REST Nexus API

first, let's run a docker container for swagger editor:

https://hub.docker.com/r/swaggerapi/swagger-editor/

docker run -d --rm --name swaggereditor -p 9080:8080 swaggerapi/swagger-editor

http://localhost:9080/


then http://localhost:8181/service/rest/swagger.json (8181 is the Nexus port) , download the file, feed it into the swagger-editor (file , import file). Import URL will not work, apparently you must be authenticated in Nexus to be able to download it.

then generate client /java , this will produce a java-client-generated.zip file with your Java client API. You extract this file, run "mvn install", then open the README.md to understand how it works...

I create a Java project, add this maven dependency

<dependencies>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-java-client</artifactId>
<version>1.0.0</version>
<scope>compile</scope>
</dependency>
</dependencies>


then try this code:

package nexusclient;

import io.swagger.client.*;
import io.swagger.client.auth.*;
import io.swagger.client.model.*;
import io.swagger.client.api.AssetsApi;

public class NexucClientTest {
 public static void main(String[] args) throws Exception {
  AssetsApi apiInstance = new AssetsApi();
  apiInstance.getApiClient().setBasePath("http://localhost:8181/service/rest");
        String continuationToken = null;
  PageAssetXO assets = apiInstance.getAssets("maven-central", continuationToken );
  for (AssetXO asset :  assets.getItems()) {
   System.out.println(asset.toString());
  }

 }

}

actually you don't even need to run swagger-editor locally, you can use the online version https://editor.swagger.io//?_ga=2.252946753.972179590.1526550450-1850471649.1526550450#/



To test, populate your nexus repos as explained here http://www.javamonamour.org/2017/09/nexus-and-maven-setup.html


If you get a 403 Unauthorized, try assigning to the user "Anonymous" the role "nx2-repository-any-full" (=nx-repository-view-*-*-*)

in the request.log you see this

127.0.0.1 - - [18/Dec/2018:17:57:01 +0100] "GET /service/rest/v1/assets?repository=central HTTP/1.1" 200 - 4698 328 "Swagger-Codegen/1.0.0/java"



Soem sample code is here

Swagger

http://petstore.swagger.io/ automatically generated console, documenting the interfaces and allowing you to test them.... better than the WSDL-based test client generator... but I wonder how much work is needed, I would hate to have to manually edit YAML files to generate this UI...

short and sweet presentation (skip first 3 minutes)





A live example here, using Spring Boot

git clone https://github.com/TechPrimers/spring-boot-swagger-example.git
cd spring-boot-swagger-example
mvn spring-boot:run

in your browser put http://localhost:8088/swagger-ui.html







Main annotations are:

io.swagger.annotations.Api (class level)

io.swagger.annotations.ApiOperation , io.swagger.annotations.ApiResponses, io.swagger.annotations.ApiResponse at method level

io.swagger.annotations.ApiModelProperty at field level


and to document the Site:
springfox.documentation.spring.web.plugins.Docket
springfox.documentation.swagger2.annotations.EnableSwagger2
etc etc

all the rest are org.springframework.web.bind.annotation annotations (GetMapping, PathVariable, RequestMapping, RestController)


This is a good tutorial https://jmchung.github.io/blog/2013/12/14/integrating-swagger-into-jax-rs-with-java-ee-6-specification/