Grain College - day 2 - Swagger

1, Swagger2 introduction

In the front end and back-end separation development mode, api documents are the best way to communicate.

Swagger is a normative and complete framework for generating, describing, invoking, and visualizing RESTful Web services.          1. Timeliness (timely and accurately notify relevant front and rear end developers after interface changes)

         2. Standardization (and ensure the standardization of the interface, such as interface address, request mode, parameters, response format and error information)

         3. Consistency (the interface information is consistent, and there will be no differences due to the inconsistent document versions obtained by the developers)

         4. Testability (test directly on the interface document to facilitate business understanding)

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", "1123@qq.com"))
                .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("{id}")
     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("{id}")
public R removeById(
     @ApiParam(name = "id", value = "lecturer ID", required = true)
     @PathVariable String id){
     teacherService.removeById(id);
     return R.ok();
}

Tags: Python Java RESTful

Posted on Tue, 07 Sep 2021 18:57:38 -0400 by steve490