Service API documentation

The API documentation of your TutorialService is defined and generated as an OpenAPI specification with the help of Springfox and Swagger. Here are the specifications about how your service API documentation is built:

1. Features are provided by the springfox-swagger2 library.

2. A configuration class SwaggerDocumentationConfig.java is generated in your service configuration package with:

   1. The @EnableSwagger2 annotation: This will add the Swagger2 configuration to your spring context. Said configuration defines beans to help automatic API documentation generation and a REST controller providing the default endpoint /v2/api-docs to retrieve said documentation.

   2. A bean of type Swagger Docket, which defines the package that should be introspected to build the OpenAPI specification returned by the /v2/api-docs endpoint:

      SwaggerDocumentationConfig.java

      @Configuration

      @EnableSwagger2

      public class SwaggerDocumentationConfig

      {

      ...

      @Bean

      public Docket customImplementation()

      {

      return new Docket(DocumentationType.SWAGGER_2)

      .select()

      .apis(RequestHandlerSelectors.basePackage("com.apiomat.microservice.tutorialservice.controller"))

      .build()

      .directModelSubstitute(java.time.LocalDate.class, java.sql.Date.class)

      .directModelSubstitute(java.time.OffsetDateTime.class, java.util.Date.class)

      .apiInfo(apiInfo());

      }

      }

3. Within the package configured in the Docket, only classes annotated with @Api will be introspected. All the controller interfaces generated for your service are annotated with it:

   IGroceryApi.java

   @Api( value = "TutorialService$1.0.0$Grocery", description = "the TutorialService$1.0.0$Grocery API", tags = { "TutorialService$1.0.0$Grocery" } )

   public interface IGroceryApi

   Each of the methods provided by your IGroceryApi interface is annotated with Swagger annotations, e.g. the update endpoint of a Grocery:

   @ApiOperation( value = "Update a Grocery", nickname = "updateGrocery", notes = "", tags = { "TutorialService$1.0.0$Grocery" } )

   @ApiResponses( value = {

   @ApiResponse( code = 200, message = "successfully updated Grocery" ),

   @ApiResponse( code = 500, message = "an error occured" ) } )

   @RequestMapping( value = "/apps/{appName}/models/TutorialService/Grocery/{dataModelId}", produces = { "application/json" }, consumes = { "application/json" }, method = RequestMethod.PUT )

   ResponseEntity<Void> updateGrocery(

   @ApiParam( value = "application name", required = true ) @PathVariable( "appName" ) final String appName,

   @ApiParam( value = "the id of the Grocery", required = true ) @PathVariable( "dataModelId" ) final String dataModelId,

   @ApiParam( value = "updated JSON of the Grocery", required = true ) @Valid @RequestBody final Grocery body );

   Only focusing on the Swagger annotations:

   - @ApiOperation gives general information about the endpoint.
   - @ApiResponse describes a response that this endpoint could return.
   - @ApiParam describes a parameter.

4. Try to retrieve the OpenAPI specification of your service by calling the default Swagger endpoint:

   curl http://{YOUR_TUTORIAL_SERVICE_HOST}/tutorialservice/v/1.0.0/v2/api-docs

The OpenAPI specification is not really human-friendly in terms of readability.

API documentation UI

Thanks to our Explorer service, any service that is registered to Consul and providing an OpenAPI specification through the default Swagger endpoint /v2/api-docs will be displayed in the ApiOmat apidocs UI:

1. Access the apidocs endpoint through your gateway (e.g. Dispatcher) host in your navigator:
   
   

   

   
   
   

2. Notice that your TutorialService endpoints are displayed (for more details about the usage of ApiDocs, refer to the Explorer documentation):
   
   

   

   
   
   

3. Additionally: If you call one of the endpoints from TutorialService in YAMBAS while using Dispatcher, the request will be proxied to your service:

   

   This request will be redirected by Dispatcher to the following TutorialService endpoint:

   GET /tutorialservice/v/1.0.0/apps/TestBe/models/TutorialService/Grocery

Next steps

• Learn how to add your own REST endpoint that you can access through the ApiDocs