JAVA-Actual-Combat-2

Java实战 (Swagger配置) 2

简介

在前后端分离的情况下，需要一个良好的接口文档，使前后端不需要太多的沟通就能按照接口文档进行工作的进行。而Swagger就是一个非常好的一个接口文档生成工具，他能够使后端开发人员不需要编写页面，只需要在对应的类上配置好注解就能够自动生成一个Swagger接口文档页面。

代码示例

1. 引入swagger依赖

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
</dependency>

2. 添加swagger配置类

package com.sevattal.service.base.config;
import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
 * @author Sevattal
 **/
@Configuration
@EnableSwagger2
public class Swagger2Config {
    /*
    * Swagger 页面默认路径为：http://localhost:port/swagger-ui.html
    *
    * */
    /*
    * 前端API
    * */
    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();
    }
    /*
    * 后端API
    * */
    @Bean
    public Docket adminApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();
    }
    /*
    * 针对于网站前端的接口描述
    * */
    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder().title("网站的api文档")
                .description("本文档描述了网站的api接口定义")
                .version("1.0")
                .contact(new Contact("Sevattal","https://sevattal.github.io","923762269@qq.com"))
                .build();
    }
    /*
     * 针对于网站管理端的接口描述
     * */
    private ApiInfo adminApiInfo(){
        return new ApiInfoBuilder().title("后台管理的api文档")
                .description("本文档描述了后台管理的api接口定义")
                .version("1.0")
                .contact(new Contact("Sevattal","https://sevattal.github.io","923762269@qq.com"))
                .build();
    }
}

2. Controller类使用 Swagger 注解参考

@Api: 注解使用在 Controller 类上，表明这个类的大致的作用
@ApiOperation(): 注解使用在 Controler 中的控制器方法上，表明该接口的作用
@ApiParam(value=””,required =true): 注解使用在 控制器方法的参数上，表明该参数的名称，该参数是否必传等。

import com.sevattal.common.base.result.R;
import com.sevattal.service.backuser.entity.BackuserRole;
import com.sevattal.service.backuser.service.BackuserRoleService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import javax.servlet.http.HttpServletRequest;
import java.util.List;
/**
 * <p>
 * 后台角色表 前端控制器
 * </p>
 *
 * @author Sevattal
 * @since 2021-04-20
 */
@Api(description = "角色管理")
@RestController
@RequestMapping("/admin/backuser/backuser-role")
@Slf4j
public class BackuserRoleController {
    @Autowired
    private BackuserRoleService backuserRoleService;
    @ApiOperation("创建角色")
    @PostMapping("createrole")
    public R createRole(@ApiParam(value = "角色名称", required = true) @RequestBody BackuserRole backuserRole){
        boolean result = backuserRoleService.createRole(backuserRole);
        if (result){
            return R.ok().message("角色创建成功");
        }else {
            return R.error().message("角色创建失败");
        }
    }
}

3. Entity 实体类 使用 Swagger 注解参考

@ApiModel: 注解使用在实体类上，表明该实体类的名称，以及其详细信息
@ApiModelProperty(value = “”): 注解使用在实体类的成员上，表明该成员的名称

package com.sevattal.service.backuser.entity;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.sevattal.service.base.model.BaseEntity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;
import lombok.experimental.Accessors;
/**
 * <p>
 * 后台角色表
 * </p>
 *
 * @author Sevattal
 * @since 2021-04-20
 */
@Data
@EqualsAndHashCode(callSuper = true)
@Accessors(chain = true)
@ApiModel(value="BackuserRole对象", description="后台角色表")
public class BackuserRole extends BaseEntity {
    private static final long serialVersionUID=1L;
    @ApiModelProperty(value = "角色名称")
    private String name;
    @ApiModelProperty(value = "排序")
    private Integer sort;
}