swagger配置即使用

矫情吗；* 2022-01-15 20:51 353阅读 0赞

先展示一下效果图

![172445\_RYG7\_3316877.png][172445_RYG7_3316877.png]

配置流程：

1.添加依赖：

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

2.swagger配置：

package com.ligowave.bill.common.config;
    
    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.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    @Configuration
    public class SwaggerConfig {
    
        @Bean
        public Docket createRestApi(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    // Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore注解的API）
                    .apis(RequestHandlerSelectors.basePackage("com.ligowave.bill.web"))
                    // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo(){
            return new ApiInfoBuilder()
                    // 页面标题
                    .title("billing api")
                    // 描述
                    .description("计费系统API接口服务文档")
                    .build();
        }
    }

3.启动类上添加@EnableSwagger2表示开启swagger注解

package com.ligowave;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @SpringBootApplication
    @EnableSwagger2
    public class ApiServiceBillingApplication {
    
    	public static void main(String[] args) {
    		SpringApplication.run(ApiServiceBillingApplication.class, args);
    	}
    }

4、restful接口：

package com.ligowave.bill.web;
    
    import com.ligowave.bill.common.bean.Response;
    import com.ligowave.bill.common.bean.ResponseCode;
    import com.ligowave.bill.common.bean.ResponseMsg;
    import com.ligowave.bill.common.bean.User;
    import com.ligowave.bill.domain.billsystem.entity.BasePackage;
    import com.ligowave.bill.domain.billsystem.vo.BasePackageEdit;
    import com.ligowave.bill.domain.billsystem.vo.BasePackageQuery;
    import com.ligowave.bill.domain.billsystem.vo.BasePackageSave;
    import com.ligowave.bill.service.BasePackageService;
    import com.ligowave.bill.web.base.BaseController;
    import io.swagger.annotations.*;
    import org.apache.commons.lang3.StringUtils;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.data.domain.Page;
    import org.springframework.http.MediaType;
    import org.springframework.web.bind.annotation.*;
    
    import javax.servlet.http.HttpServletRequest;
    import java.util.List;
    
    @Api(value = "BasePackageController", tags = {"套餐操作接口"})
    @RestController
    public class BasePackageController extends BaseController {
        @Autowired
        BasePackageService basePackageService;
    
        /**
         * 获取套餐的分页列表
         */
        @ApiOperation(value = "高级搜索获取套餐的分页列表")
        @ApiImplicitParam(name = "basePackageQuery", value = "套餐列表查询条件对象", required = true, dataType = "BasePackageQuery")
        @RequestMapping(value = "/basepackage/basepackages", method = {RequestMethod.POST}, produces = MediaType.APPLICATION_JSON_VALUE)
        public Page<BasePackage> pageList(@RequestBody BasePackageQuery basePackageQuery) {
            return basePackageService.findPageList(basePackageQuery);
        }
    
        /**
         * 根据id获取套餐的详细信息
         */
        @ApiOperation(value = "根据id获取套餐的详细信息")
        @ApiImplicitParam(name = "id", value = "套餐ID", required = true, dataType = "Integer",paramType = "path")
        @RequestMapping(value = "/basepackage/{id}", method = RequestMethod.GET)
        public Response<BasePackage> getById(@PathVariable(value = "id") Integer id) {
            BasePackage basePackage = basePackageService.getById(id);
            if (null != basePackage) {
                return new Response<>(ResponseCode.SUCCESS, ResponseMsg.SUCCESS, basePackage);
            } else {
                return new Response<>(ResponseCode.UNKNOWN_ERROR, ResponseMsg.UNKNOWN_ERROR, null);
            }
        }
    
        /**
         * 修改套餐
         */
        @ApiOperation(value = "更新套餐信息",notes="根据url的id来指定更新对象，并根据传过来的basePackageEdit信息来更新套餐详细信息")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"),
                @ApiImplicitParam(name = "basePackageEdit", value = "套餐详细实体", required = true, dataType = "BasePackageEdit")
        })
        @RequestMapping(value = "/basepackage/{id}", method = RequestMethod.PUT)
        public Response<BasePackage> update(@PathVariable(value = "id") Integer id,
                                            @RequestBody BasePackageEdit basePackageEdit) {
            BasePackage basePackage = basePackageService.update(id, basePackageEdit);
            return new Response<>(ResponseCode.SUCCESS, ResponseMsg.SUCCESS, basePackage);
        }
    
        /**
         * 根据id删除套餐
         */
        @ApiOperation(value = "删除套餐",notes="根据url的id来指定删除对象")
        @ApiImplicitParam(name = "id", value = "套餐ID", required = true, dataType = "Integer",paramType = "path")
        @RequestMapping(value = "/basepackage/{id}", method = RequestMethod.DELETE)
        public Response<BasePackage> deleteById(@PathVariable(value = "id") Integer id) {
            try {
                basePackageService.deleteByID(id);
            } catch (Exception e) {
                e.printStackTrace();
                return new Response<>(ResponseCode.UNKNOWN_ERROR, ResponseMsg.UNKNOWN_ERROR, null);
            }
            return new Response<>(ResponseCode.SUCCESS, ResponseMsg.SUCCESS, null);
        }
    
        /**
         * 添加套餐
         */
        @ApiOperation(value = "添加套餐")
        @ApiImplicitParam(name = "basePackageSave", value = "套餐详细实体", required = true,dataType = "BasePackageSave")
        @RequestMapping(value = "/basepackage", method = RequestMethod.POST)
        public Response<BasePackage> save(@RequestBody  BasePackageSave basePackageSave, HttpServletRequest request) {
            User user = getCurrentEmployee(request);
            //校验套餐名称、下架时间、最大出账周期、套餐价格不能为空
            if (StringUtils.isBlank(basePackageSave.getName()) || StringUtils.isBlank(basePackageSave.getEndTimeStr()) || basePackageSave.getMaximumAccount() == null ||
                    basePackageSave.getPackagePrice() == null) {
                return new Response<>(ResponseCode.PACKAGE_PARAM_ERROR, ResponseMsg.PACKAGE_PARAM_ERROR, null);
            }
            //校验套餐名称是否存在
            if (checkNameExist(basePackageSave.getName(), user.getOrgid())) {
                return new Response<>(ResponseCode.PACKAGE_EXISTED, ResponseMsg.PACKAGE_EXISTED, null);
            }
            basePackageService.save(basePackageSave);
            return new Response<>(ResponseCode.SUCCESS, ResponseMsg.SUCCESS, null);
        }
    
    
        /**
         * 根据套餐名和组织ID验证唯一性
         */
        private boolean checkNameExist(String name, String orgId) {
            boolean exist = false;
            if (!StringUtils.isBlank(name)) {
                List<BasePackage> list = basePackageService.findByNameAndOrgId(name, orgId);
                if (null != list && list.size() > 0) {
                    exist = true;
                }
            }
            return exist;
        }
    }

上述用到的swagger注解有：

**@Api()**用于类

**@ApiOperation()**用于方法

**@ApiParam()**用于方法，参数，字段说明

5.用于接收传入参数的对象：

package com.ligowave.bill.domain.billsystem.vo;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    
    /**
     * 套餐列表搜索条件
     */
    @ApiModel(description = "套餐列表查询条件")
    public class BasePackageQuery extends BaseQuery {
        @ApiModelProperty(value = "套餐名称", dataType = "String")
        private String name;
        @ApiModelProperty(value = "描述", dataType = "String")
        private String description;
        @ApiModelProperty(value = "是否被引用", dataType = "Integer", notes = "0-是,1-否")
        private Integer whetherReferenced;
        @ApiModelProperty(value = "发布时间始于", dataType = "String", notes = "格式为：yyyy-MM-dd HH:mm:ss")
        private String beforeBegintime;
        @ApiModelProperty(value = "发布时间终于", dataType = "String", notes = "格式为：yyyy-MM-dd HH:mm:ss")
        private String afterBegintime;
        @ApiModelProperty(value = "组织ID", dataType = "String")
        private String orgId;
    
        public String getName() {
            return name;
        }
    
        public void setName(String name) {
            this.name = name;
        }
    
        public String getDescription() {
            return description;
        }
    
        public void setDescription(String description) {
            this.description = description;
        }
    
        public String getBeforeBegintime() {
            return beforeBegintime;
        }
    
        public void setBeforeBegintime(String beforeBegintime) {
            this.beforeBegintime = beforeBegintime;
        }
    
        public String getAfterBegintime() {
            return afterBegintime;
        }
    
        public void setAfterBegintime(String afterBegintime) {
            this.afterBegintime = afterBegintime;
        }
    
        public Integer getWhetherReferenced() {
            return whetherReferenced;
        }
    
        public void setWhetherReferenced(int whetherReferenced) {
            this.whetherReferenced = whetherReferenced;
        }
    
        public String getOrgId() {
            return orgId;
        }
    
        public void setOrgId(String orgId) {
            this.orgId = orgId;
        }
    }

效果图展示：

![174049\_pvxX\_3316877.png][174049_pvxX_3316877.png]

上述用到的注解：

*  **@ApiModel**：用对象来接收参数
 *  **@ApiModelProperty()**用于方法，字段； 表示对model属性的说明或者数据操作更改

6.swagger默认访问地址为：http://localhost:8080/swagger-ui.html

转载于:https://my.oschina.net/wuyiyi/blog/1605748

[172445_RYG7_3316877.png]: https://static.oschina.net/uploads/space/2018/0111/172445_RYG7_3316877.png
[174049_pvxX_3316877.png]: https://static.oschina.net/uploads/space/2018/0111/174049_pvxX_3316877.png