Taymyr: Openapi Java

OpenAPI service for Lagom framework

License

License

Categories

Categories

Java Languages
GroupId

GroupId

org.taymyr
ArtifactId

ArtifactId

openapi-java
Last Version

Last Version

0.0.1
Release Date

Release Date

Type

Type

pom
Description

Description

Taymyr: Openapi Java
OpenAPI service for Lagom framework
Project URL

Project URL

https://taymyr.org
Project Organization

Project Organization

Digital Economy League
Source Code Management

Source Code Management

https://github.com/taymyr/openapi-java

Download openapi-java

Filename Size
openapi-java-0.0.1.pom 8 KB
Browse

How to add to project

<!-- https://jarcasting.com/artifacts/org.taymyr/openapi-java/ -->
<dependency>
    <groupId>org.taymyr</groupId>
    <artifactId>openapi-java</artifactId>
    <version>0.0.1</version>
    <type>pom</type>
</dependency>
// https://jarcasting.com/artifacts/org.taymyr/openapi-java/
implementation 'org.taymyr:openapi-java:0.0.1'
// https://jarcasting.com/artifacts/org.taymyr/openapi-java/
implementation ("org.taymyr:openapi-java:0.0.1")
'org.taymyr:openapi-java:pom:0.0.1'
<dependency org="org.taymyr" name="openapi-java" rev="0.0.1">
  <artifact name="openapi-java" type="pom" />
</dependency>
@Grapes(
@Grab(group='org.taymyr', module='openapi-java', version='0.0.1')
)
libraryDependencies += "org.taymyr" % "openapi-java" % "0.0.1"
[org.taymyr/openapi-java "0.0.1"]

Dependencies

There are no dependencies for this project. It is a standalone project that does not depend on any other jars.

Project Modules

  • api
  • impl

Gitter Gitter_RU Build Status codecov Maven

OpenAPI/Swagger module for Lagom

The Lagom OpenAPI module has two common features:

  • Generation OpenAPI 3.X specification for the Lagom service by annotations. (How to use with Scala DSL/Java DSL)
  • Publishing static OpenAPI 3.X/Swagger 2.X specification from the classpath. (How to use with Scala DSL/Java DSL)

Also, you can see how to generate OpenAPI Specification for Lagom service on demo projects (Java/Maven example, Scala/Sbt example).

Versions compatibility

Lagom OpenAPI OpenAPI / Swagger Lagom 1.4 Lagom 1.5 Lagom 1.6 Scala 2.11 Scala 2.12 Scala 2.13
1.+ 2.0.7+

How to use

1.1 Generate (Scala DSL)

1.1.1 Dependencies

You need to add next dependencies to the API module of Lagom service:

val swaggerAnnotations = "io.swagger.core.v3" % "swagger-annotations" % "2.0.7"
val lagomOpenapiApi = "org.taymyr.lagom" %% "lagom-openapi-scala-api" % lagomOpenapiVersion

lazy val `lagom-service-api` = (project in file("api"))
  .settings(
    libraryDependencies ++= Seq(
      ...
      swaggerAnnotations,
      lagomOpenapiApi
    )
  )

and next dependencies to the Implementation module of Lagom service:

val lagomOpenapiImpl = "org.taymyr.lagom" %% "lagom-openapi-scala-impl" % lagomOpenapiVersion

lazy val `lagom-service-impl` = (project in file("impl"))
  .enablePlugins(LagomScala)
  .settings(
    libraryDependencies ++= Seq(
      ...
      lagomOpenapiImpl
    )
  )

1.1.2 Service Descriptor

Necessarily add OpenAPIDefinition annotation to Lagom service descriptor and extend descriptor by OpenAPIService trait:

@OpenAPIDefinition(
  info = new Info(
    version = "1.0.0",
    title = "My Service"
  ),
  ...
)
trait MyService extends OpenAPIService with Service {
  ...
}

Then you can use OpenAPI annotations for the methods of your service. For more information about annotations see the official wiki.

@Operation(...)
@Tag(...)
...
def method: ServiceCall[_, _]

In conclusion, you must add the route for OpenAPI specification. You can do that with helper function withOpenAPI (default route is /_<service_name>/openapi)

override def descriptor: Descriptor = named("service")
    .withOpenAPI()
    ...

or use a custom route

override def descriptor: Descriptor = named("service")
    .withCalls(
      ...
      pathCall("/custom/route", openapi)
    )

1.1.3 Service implementation

Extend your service by the OpenAPIServiceImpl trait:

class MyServiceImpl(override val config: Config)
    extends MyService
    with OpenAPIServiceImpl {
      ...
}

1.1.4 Conclusion

Now you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:

curl "http://localhost:9000/_<service_name>/openapi[?format=json|yaml]"

1.2 Generate (Java DSL)

1.2.1 Dependencies

You need to add next dependencies to the API module of Lagom service:

Maven

<dependencies>
    <dependency>
        <groupId>org.taymyr.lagom</groupId>
        <artifactId>lagom-openapi-java-api_${scala.binary.version}</artifactId>
        <version>${lagom.openapi.version}</version>
    </dependency>
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>2.0.7</version>
    </dependency>
</dependencies>

Sbt

val swaggerAnnotations = "io.swagger.core.v3" % "swagger-annotations" % "2.0.7"
val lagomOpenapiApi = "org.taymyr.lagom" %% "lagom-openapi-java-api" % lagomOpenapiVersion

lazy val `lagom-service-api` = (project in file("api"))
  .settings(
    libraryDependencies ++= Seq(
      ...
      swaggerAnnotations,
      lagomOpenapiApi
    )
  )

and next dependencies to the Implementation module of Lagom service:

Maven

<dependencies>
    <dependency>
        <groupId>org.taymyr.lagom</groupId>
        <artifactId>lagom-openapi-java-impl_${scala.binary.version}</artifactId>
        <version>${lagom.openapi.version}</version>
    </dependency>
</dependencies>

Sbt

val lagomOpenapiImpl = "org.taymyr.lagom" %% "lagom-openapi-java-impl" % lagomOpenapiVersion

lazy val `lagom-service-impl` = (project in file("impl"))
  .enablePlugins(LagomScala)
  .settings(
    libraryDependencies ++= Seq(
      ...
      lagomOpenapiImpl
    )
  )

1.2.2 Service Descriptor

Necessarily add OpenAPIDefinition annotation to Lagom service descriptor and extend descriptor by OpenAPIService interface:

@OpenAPIDefinition(
  info = @Info(
    version = "1.0.0",
    title = "My Service"
  ),
  ...
)
public interface MyService extends OpenAPIService {
  ...
}

Then you can use OpenAPI annotations for the methods of your service. For more information about annotations see the official wiki.

@Operation(...)
@Tag(...)
...
ServiceCall<_, _> method();

In conclusion, you must add the route for OpenAPI specification. You can do that with helper function withOpenAPI (default route is /_<service_name>/openapi)

@Override
default Descriptor descriptor() {
  return withOpenAPI(
    named("service")
      ...
  );
}

or use a custom route

@Override
default Descriptor descriptor() {
  return named("service")
    .withCalls(
      ...
      pathCall("/custom/route", this::openapi)
    );
}

1.2.3 Service implementation

Extend your service by the abstract AbstractOpenAPIService:

public class MyServiceImpl extends AbstractOpenAPIService implements MyService {
      ...
}

1.2.4 Conclusion

Now you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:

curl "http://localhost:9000/_<service_name>/openapi[?format=json|yaml]"

2.1 Static (Scala DSL)

2.1.1 Dependencies

You need to add next dependencies to the API module of Lagom service:

val lagomOpenapiApi = "org.taymyr.lagom" %% "lagom-openapi-scala-api" % lagomOpenapiVersion

lazy val `lagom-service-api` = (project in file("api"))
  .settings(
    libraryDependencies ++= Seq(
      ...
      lagomOpenapiApi
    )
  )

and next dependencies to the Implementation module of Lagom service:

val lagomOpenapiImpl = "org.taymyr.lagom" %% "lagom-openapi-scala-impl" % lagomOpenapiVersion

lazy val `lagom-service-impl` = (project in file("impl"))
  .enablePlugins(LagomScala)
  .settings(
    libraryDependencies ++= Seq(
      ...
      lagomOpenapiImpl
    )
  )

2.1.2 Service Descriptor

Extend Lagom service descriptor by OpenAPIService trait:

trait MyService extends OpenAPIService with Service {
  ...
}

Add OpenAPI/Swagger specification file to classpath (typically src/main/resources folder) of API module. By default, the file should be named <service_name>.[yml|yaml|json].

openapi: 3.0.0
info:
  title: My Service
  version: 1.0.0
paths:
  ...

Also, you can change filename using openapi.file configuration in application.conf.

openapi.file = foobar.yml

In conclusion, you must add the route for OpenAPI specification. You can do that with helper function withOpenAPI (default route is /_<service_name>/openapi)

override def descriptor: Descriptor = withOpenAPI(
  named("service")
    ...
)

or use a custom route

override def descriptor: Descriptor = named("service")
    .withCalls(
      ...
      pathCall("/custom/route?format", openapi)
    )

2.1.3 Service implementation

Extend your service by the OpenAPIServiceImpl trait:

class MyServiceImpl(override val config: Config)
    extends MyService
    with OpenAPIServiceImpl {
      ...
}

2.1.4 Conclusion

Now you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:

curl "http://localhost:9000/_<service_name>/openapi[?format=json|yaml]"

2.2 Static (Java DSL)

2.2.1 Dependencies

You need to add next dependencies to the API module of Lagom service:

Maven

<dependencies>
    <dependency>
        <groupId>org.taymyr.lagom</groupId>
        <artifactId>lagom-openapi-java-api_${scala.binary.version}</artifactId>
        <version>${lagom.openapi.version}</version>
    </dependency>
</dependencies>

Sbt

val lagomOpenapiApi = "org.taymyr.lagom" %% "lagom-openapi-java-api" % lagomOpenapiVersion

lazy val `lagom-service-api` = (project in file("api"))
  .settings(
    libraryDependencies ++= Seq(
      ...
      lagomOpenapiApi
    )
  )

and next dependencies to the Implementation module of Lagom service:

Maven

<dependencies>
    <dependency>
        <groupId>org.taymyr.lagom</groupId>
        <artifactId>lagom-openapi-java-impl_${scala.binary.version}</artifactId>
        <version>${lagom.openapi.version}</version>
    </dependency>
</dependencies>

Sbt

val lagomOpenapiImpl = "org.taymyr.lagom" %% "lagom-openapi-java-impl" % lagomOpenapiVersion

lazy val `lagom-service-impl` = (project in file("impl"))
  .enablePlugins(LagomScala)
  .settings(
    libraryDependencies ++= Seq(
      ...
      lagomOpenapiImpl
    )
  )

2.2.2 Service Descriptor

Extend Lagom service descriptor by OpenAPIService interface:

public interface MyService extends OpenAPIService {
  ...
}

Add OpenAPI/Swagger specification file to classpath (typically src/main/resources folder) of API module. By default, the file should be named <service_name>.[yml|yaml|json].

openapi: 3.0.0
info:
  title: My Service
  version: 1.0.0
paths:
  ...

Also, you can change filename using openapi.file configuration in application.conf.

openapi.file = foobar.yml

In conclusion, you must add the route for OpenAPI specification. You can do that with helper function org.taymyr.lagom.javadsl.openapi.OpenAPIUtils#withOpenAPI (default route is /_<service_name>/openapi)

@Override
default Descriptor descriptor() {
  return withOpenAPI(
    named("service")
      ...
  );
}

or use a custom route

@Override
default Descriptor descriptor() {
  return named("service")
    .withCalls(
      ...
      pathCall("/custom/route?format", this::openapi)
    );
}

2.2.3 Service implementation

Extend your service by the abstract AbstractOpenAPIService:

public class MyServiceImpl extends AbstractOpenAPIService implements MyService {
      ...
}

2.2.4 Conclusion

Now you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:

curl "http://localhost:9000/_<service_name>/openapi[?format=json|yaml]"

Contributions

Contributions are very welcome.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

org.taymyr

Taymyr

Microservices business platform

Versions

Version
0.0.1