Tuesday, 16 January 2018

Spring boot +Swagger + Pretty Swag

This post describes how to build a a Rest Api with Spring  Boot and Swagger. The tutorial adds additional rest api functionality to an existing spring boot application.

1. Add the following maven dependencies

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.6.1</version>
</dependency>

<!-- optional to produce swagger ui -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.6.1</version>
</dependency>

2. Create swagger configuration class

@Configuration@EnableSwagger2
public class SwaggerConf {
  @Bean public Docket api() {
    ApiInfo apiInfo = new ApiInfo("My Store","Api for the store backend", "1.0", "", new Contact("Riz", "http://rizvn.com", "me@example.com"),"", "");

    return new Docket(DocumentationType.SWAGGER_2)
    .select()
    .apis(RequestHandlerSelectors.any())
    .paths(Predicates.or(
      PathSelectors.regex("/store.*"),    //expose paths starting with /store
      PathSelectors.regex("/health.*")  //expose paths staring with  /health
    )) 
    .build()
    .apiInfo(apiInfo);
  }
}

3. Create a rest controller

@RestController(value ="Rest Api" )
@io.swagger.annotations.Api(value = "/store", description = "Store Rest Api Operations")
@RequestMapping("/store")
public class RestApi
{

  @Resource ProductService productService;
  @Resource OrderService orderService;

  @ApiOperation(value = "Find a product by id")
  @RequestMapping(path = "/product/{id}", method = RequestMethod.GET)
  public Product getProduct(@PathVariable("id") String aId)
  {
    return productService.read(aId);
  }


  @ApiOperation(value = "Find a order by id")
  @RequestMapping(path = "/order/{id}", method = RequestMethod.GET)
  public Order getOrder(@PathVariable("id") String aId)
  {
    return orderService.read(aId); 
  }
}

Both methods return java objects. Spring Boot will automatically handle the conversion to json through jackson. 

On startup the api json schema will be available at under v2/api-docs. For example: 
(Port number will vary per app)

An interactive Swagger UI will be available swagger-ui.html. Swagger UI is an interactive single page application allowing to interactively test your api. 
(Port number will vary per app)


Offline Documentation

Its great to have online documentation of a rest endpoint. However during development we may need to share our api with other developers, so they may build applications against the api, before the application is built. The api is a contract, stating which functions the application supports. 
Pretty Swag is nice utility, to produce an offline version the rest api documentation. see: https://www.npmjs.com/package/pretty-swag

To provide an offline version of the application api. First start the application. 

1. Install Node.js on your machine if not already installed. 


2. Install pretty-swag

npm install pretty-swag -g
-g installs globally

3. Generate offline documentation

pretty-swag -i http://localhost:7070/v2/api-docs -f offline
This will produce a doc.html file, and doc_files directory which can be distributed independently.  http://localhost:7070/v2/api-docs points to the running instance of our development application. 



3 comments:

  1. The effectiveness of IEEE Project Domains depends very much on the situation in which they are applied. In order to further improve IEEE Final Year Project Domains practices we need to explicitly describe and utilise our knowledge about software domains of software engineering Final Year Project Domains for CSE technologies. This paper suggests a modelling formalism for supporting systematic reuse of software engineering technologies during planning of software projects and improvement programmes in Final Year Project Centers in Chennai.

    Spring Framework has already made serious inroads as an integrated technology stack for building user-facing applications. Spring Framework Corporate TRaining the authors explore the idea of using Java in Big Data platforms.
    Specifically, Spring Framework provides various tasks are geared around preparing data for further analysis and visualization. Spring Training in Chennai

    ReplyDelete