Springboot integrates third-party Swagger-Bootstrap-UI beautification document styles

This demo shows how to integrate a third-party Swagger to replace the native Swagger and beautify the document style. This demo uses swagger-bootstrap-ui to start the project at http://${host}:${port}/doc.html

The UI enhancements

Swagger-bootstrap-ui not only meets the above functions, but also provides enhanced document functions, which are not available in the official Swagger-UI. Each enhanced function is suitable for the actual development needs of developers, and is indispensable, mainly including:

• Personalized UI configuration: You can customize UI display information by personalized UI configuration items

• Offline Documentation: The swagger2Markdown component can also be discarded by developers who can copy the online Markdown offline documentation generated according to the standard specification and convert the Markdown interface documentation to HTML or PDF using other third-party Markdown conversion tools

• Interface sorting: Since 1.8.5, UI supports interface sorting. For example, a registration function mainly contains multiple steps. Interfaces can be sorted according to the interface sorting rules provided by Swagger-Bootstrap-UI

The UI features

• The document is displayed in markdown form, and the request address, type, request parameters, example and response parameters of the document are displayed in hierarchical order. The interface document is clear at a glance, which is convenient for developers to connect
• In addition to automatically parsing parameters, the online debugging bar distinguishes required fields by color and supports quick TAB key input to switch up and down. You can customize the content-type request header Type during debugging
• Personalized configuration item: supports personalized configuration functions such as interface address, interface description attribute, and UI enhancement
• Interface sorting: supports grouping and interface sorting
• You can export markdown documents offline and view offline documents online
• Debug information global cache, page refresh still exist, convenient developer debugging
• Showcasing Swagger Models functionality with a more user-friendly Treetable component
• The response content can be viewed in full screen, facilitating debugging and replication
• Document Multiple interface documents can be displayed in multi-tab mode
• Request parameter field Request type, whether to fill in color distinction
• The home page roughly counts the number of different interface types
• Supports the online interface search function
• Left and right menus and content pages can be freely dragged width
• Supports custom global parameters. The home page can be header and Query
• I18n internationalization support, currently support: Simplified Chinese, Traditional Chinese, English
• Jsr-303 Annotations support

use

Maven rely on

Since springfox-Swagger is an enhanced UI package, the basic functionality still depends on Swagger, and the Springfox-Swagger JAR package must be introduced

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>
Copy the code

Then import the SwaggerBootstrapUi JAR package

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>swagger-bootstrap-ui</artifactId>
  <version>1.9.6</version>
</dependency>
Copy the code

Write the Swagger2Config configuration file

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

 @Bean
 public Docket createRestApi(a) {  return new Docket(DocumentationType.SWAGGER_2)  .apiInfo(apiInfo())  .select()  .apis(RequestHandlerSelectors.basePackage("com.bycdao.cloud"))  .paths(PathSelectors.any())  .build();  }   private ApiInfo apiInfo(a) {  return new ApiInfoBuilder()  .title("swagger-bootstrap-ui RESTful APIs")  .description("swagger-bootstrap-ui")  .termsOfServiceUrl("http://localhost:8999/")  .version("1.0")  .build();  } } Copy the code

ApiResponse.java

package cn.haoxiaoyong.swagger.enhance.common;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Builder; import lombok.Data; import lombok.NoArgsConstructor;  import java.io.Serializable;  / * * * @authorHaoxiaoyong on 2020/5/14 3:55 PM * e-mail: [email protected]  * github: https://github.com/haoxiaoyong1014  * Blog: www.haoxiaoyong.cn * / @Data @Builder @NoArgsConstructor @AllArgsConstructor @ApiModel(value = "Universal PI interface return", description = "Common Api Response") public class ApiResponse<T> implements Serializable {  private static final long serialVersionUID = -8987146499044811408L;  / * ** Universal return status* /  @ApiModelProperty(value = "General return state", required = true)  private Integer code;  / * ** Generic return information* /  @ApiModelProperty(value = "General return message", required = true)  private String message;  / * ** Universal return data* /  @ApiModelProperty(value = "Universal return data", required = true)  private T data; }  Copy the code

User.java

package cn.haoxiaoyong.swagger.enhance.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data; import lombok.NoArgsConstructor;  / * * * @authorHaoxiaoyong on 2020/5/14 3:56 PM * e-mail: [email protected]  * github: https://github.com/haoxiaoyong1014  * Blog: www.haoxiaoyong.cn * /  @Data @NoArgsConstructor @AllArgsConstructor @ApiModel(value = "User entity", description = "User Entity") public class User {   private static final long serialVersionUID = 5057954049311281252L;  / * ** the primary key id* /  @ApiModelProperty(value = "The primary key id", required = true)  private Integer id;  / * ** user name* /  @ApiModelProperty(value = "Username", required = true)  private String name;  / * ** Jobs* /  @ApiModelProperty(value = "工作岗位", required = true)  private String job; }  Copy the code

UserController.java

package cn.haoxiaoyong.swagger.enhance.controller;

import cn.haoxiaoyong.swagger.enhance.common.ApiResponse;
import cn.haoxiaoyong.swagger.enhance.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.*; import org.springframework.web.multipart.MultipartFile;  import java.util.List;  / * * * @authorHaoxiaoyong on 2020/5/14 3:54pm * e-mail: [email protected]  * github: https://github.com/haoxiaoyong1014  * Blog: www.haoxiaoyong.cn * / @RestController @RequestMapping("/user") @Api(tags = "1.0.0 - the SNAPSHOT", description = "User Management", value = "User Management") @Slf4j public class UserController {   @GetMapping  @ApiOperation(value = "Conditional Query (DONE)", notes = "Note")  @ApiImplicitParams({@ApiImplicitParam(name = "username", value = "Username", defaultValue = "xxx")})  public ApiResponse<User> getByUserName(String username) {  log.info("Use @apiIMPLicitParams for multiple parameters");  return ApiResponse.<User>builder().code(200).message("Operation successful").data(new User(1, username, "JAVA")).build();  }   @GetMapping("/{id}")  @ApiOperation(value = "Primary key query (DONE)", notes = "Note")  @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "User Number",dataType = "int")})  public ApiResponse<User> get(@PathVariable Integer id) {  log.info("Single parameter @apiIMPLicitParam");  return ApiResponse.<User>builder().code(200).message("Operation successful").data(new User(id, "u1"."p1")).build();  }   @DeleteMapping("/{id}")  @ApiOperation(value = "Delete user (DONE)", notes = "Note")  @ApiImplicitParam(name = "id", value = "User Number",dataType = "int")  public void delete(@PathVariable Integer id) {  log.info("ApiImplicitParam for a single parameter");  }   @PostMapping  @ApiOperation(value = "Add user (DONE)")  public User post(@RequestBody User user) {  log.info("If it's a POST PUT with an @requestbody you don't have to say @apiIMPLicitParam.");  return user;  }   @PostMapping("/multipar")  @ApiOperation(value = "Add user (DONE)")  public List<User> multipar(@RequestBody List<User> user) {  log.info("If it's a POST PUT with an @requestbody you don't have to say @apiIMPLicitParam.");   return user;  }   @PostMapping("/array")  @ApiOperation(value = "Add user (DONE)")  public User[] array(@RequestBody User[] user) {  log.info("If it's a POST PUT with an @requestbody you don't have to say @apiIMPLicitParam.");  return user;  }   @PutMapping("/{id}")  @ApiOperation(value = "Modify user (DONE)")  public void put(@PathVariable Long id, @RequestBody User user) {  log.info("If you don't want to write @apiIMPLicitParam then Swagger will use the default parameter name as its description.");  }   @PostMapping("/{id}/file")  @ApiOperation(value = File upload (DONE))  public String file(@PathVariable Long id, @RequestParam("file") MultipartFile file) {  log.info(file.getContentType());  log.info(file.getName());  log.info(file.getOriginalFilename());  return file.getOriginalFilename();  } }  Copy the code

UI

Address of this case