Swagger Adoption

Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment. This is a brief introduction about Swagger adoption. This documentation is written based on SpringBoot.

Import Swagger and UI

Import Swagger and its embed UI by maven dependency:

maven dependency

<properties>      <swagger.version> 2.6 . 1 </swagger.version>      <swagger.ui.version> 2.2 . 2 </swagger.ui.version> </properties>   <dependencies>      <dependency>      <groupId>io.springfox</groupId>      <artifactId>springfox-swagger2</artifactId>      <version>${swagger.version}</version> </dependency> <dependency>      <groupId>io.springfox</groupId>      <artifactId>springfox-swagger-ui</artifactId>      <version>${swagger.ui.version}</version> </dependency> </dependencies>

Enable Swagger in Application

Enable Swagger in App

@SpringBootApplication @EnableSwagger2 public  class  App {        public  static  void  main(String[] args) {          SpringApplication.run(App. class , args);      }        @Bean      public  Docket config() {          return  new  Docket(DocumentationType.SWAGGER_2)                  .select()                  .apis(RequestHandlerSelectors.basePackage( "com.mytest.controller" ))                  .build()                  .apiInfo(apiInfo());      }        private  ApiInfo apiInfo() {          return  new  ApiInfoBuilder()                  .title( "My Service" )                  .build();      }   }

Adopt in API Design

Here is a sample of Swagger adoption in API code:

Adopt in API

@Api (description =  "My Service" ) public  class  MyController {        @ApiOperation (value =  "Do something" , notes =  "This api is for test" , tags =  "Do something" , response = MyResponse. class )      @ApiResponses (value = {          @ApiResponse (code =  200 , message =  "OK" , response = MyResponse. class ),          @ApiResponse (code =  400 , message =  "Bad Request" ),          @ApiResponse (code =  401 , message =  "Unauthorized" ),          @ApiResponse (code =  500 , message =  "Internal server error" )      })      public  MyResponse myMethod( ) {          ...      } }

Launch Swagger UI

Launch the Application and trigger Swagger UI by url: http://<host>:<port>/<context_path>/swagger-ui.html

In the provided UI page, user could try the API out and read the API description, request and response parameters. Since Swagger is annotated in the API code, developer could also save a lot of time and effort maintaining the API documentation. Hence it is a very convenient tool for both developer and API users.

Reference

For more detailed information, please refer to https://swagger.io/.