Grain College - day 2 - Swagger

2, Configure Swagger2

1. Create common module

Create the module common under Guli parent

to configure:

groupId: com.atguigu

artifactId: common

2. Introduce related dependencies in common

<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <scope>provided </scope> </dependency> <!--mybatis-plus--> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <scope>provided </scope> </dependency> <!--lombok Used to simplify entity classes: need to install lombok plug-in unit--> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <scope>provided </scope> </dependency> <!--swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <scope>provided </scope> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <scope>provided </scope> </dependency> <!-- redis --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis</artifactId> </dependency> <!-- spring2.X integrate redis what is needed common-pool2 <dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-pool2</artifactId> <version>2.6.0</version> </dependency>--> </dependencies>

3. Create a sub module service base under common

Create the package com.atguigu.servicebase.config and create the class SwaggerConfig

@Configuration //Configuration class @EnableSwagger2 //swagger annotation public class SwaggerConfig { @Bean public Docket webApiConfig(){ return new Docket(DocumentationType.SWAGGER_2) .groupName("webApi") .apiInfo(webApiInfo()) .select() .paths(Predicates.not(PathSelectors.regex("/admin/.*"))) .paths(Predicates.not(PathSelectors.regex("/error.*"))) .build(); } private ApiInfo webApiInfo(){ return new ApiInfoBuilder() .title("website-Course Center API file") .description("This document describes the microservice interface definition of the course center") .version("1.0") .contact(new Contact("java", "http://atguigu.com", "[email protected]")) .build(); } }

4. Introduce service base into service module  

<dependency> <groupId>com.atguigu</groupId> <artifactId>service-base</artifactId> <version>0.0.1-SNAPSHOT</version> </dependency>

5. Add annotations on the service edu startup class for testing

6. API model

You can add some custom settings, such as defining sample data

@ApiModelProperty(value = "Creation time", example = "2019-01-01 8:00:00") @TableField(fill = FieldFill.INSERT) private Date gmtCreate; @ApiModelProperty(value = "Update time", example = "2019-01-01 8:00:00") @TableField(fill = FieldFill.INSERT_UPDATE) private Date gmtModified;

  5. Define interface description and parameter description

Defined on class: @ Api

Defined on method: @ ApiOperation

Defined on parameter: @ ApiParam

@Api(description="Instructor management") @RestController @RequestMapping("/admin/edu/teacher") public class TeacherAdminController { @Autowired private TeacherService teacherService; @ApiOperation(value = "List of all instructors") @GetMapping public List<Teacher> list(){ return teacherService.list(null); } @ApiOperation(value = "according to ID Delete instructor") @DeleteMapping("") public boolean removeById( @ApiParam(name = "id", value = "lecturer ID", required = true) @PathVariable String id){ return teacherService.removeById(id); } }

1, Unified return data format

In the project, we will package the response into json return. Generally, we will unify the data format of all interfaces to make the data operation of the front end (IOS, Android, web) more consistent and easy.

Generally, the unified return data format has no fixed format, as long as it can clearly describe the returned data status and the specific data to be returned. However, it usually includes status code, return message and data

For example, the basic data format required by our system is as follows:

List:

  Pagination:

No data returned:

  Failed:

Therefore, we define uniform results  

2, Create a unified result return class  

1. Create a sub module common utils under the common module

2. Create interface definition return code

Create the package com.atguigu.commonutils and the interface ResultCode.java

public interface ResultCode { public static Integer SUCCESS = 2000;//success public static Integer ERROR = 2001;//operation failed }

3. Create result class

Create class R.java

@Data //Unified return result class public class R { @ApiModelProperty(value = "Is it successful") private Boolean success; @ApiModelProperty(value = "Return code") private Integer code; @ApiModelProperty(value = "Return message") private String message; @ApiModelProperty(value = "Return data") private Map<String, Object> data = new HashMap<String, Object>(); //Construction method private private R(){} //Successful static method public static R ok(){ R r = new R(); r.setSuccess(true); r.setCode(ResultCode.SUCCESS); r.setMessage("success"); return r; } //Failed static method public static R error(){ R r = new R(); r.setSuccess(false); r.setCode(ResultCode.ERROR); r.setMessage("fail"); return r; } public R success(Boolean success){ this.setSuccess(success); return this; } public R message(String message){ this.setMessage(message); return this; } public R code(Integer code){ this.setCode(code); return this; } public R data(String key, Object value){ this.data.put(key, value); return this; } public R data(Map<String, Object> map){ this.setData(map); return this; } }

2, Unified use of returned results

1. Add dependency in service module

<dependency> <groupId>com.atguigu</groupId> <artifactId>common_utils</artifactId> <version>0.0.1-SNAPSHOT</version> </dependency>

2. Modify the returned results in the Controller

list

@ApiOperation(value = "List of all instructors") @GetMapping public R list(){ List<Teacher> list = teacherService.list(null); return R.ok().data("items", list); }

delete

@ApiOperation(value = "according to ID Delete instructor") @DeleteMapping("") public R removeById( @ApiParam(name = "id", value = "lecturer ID", required = true) @PathVariable String id){ teacherService.removeById(id); return R.ok(); }

Add new comment

0 comments