使用Swagger2構建強大的springboot開發文檔

一、Swagger2

       在項目中，經常需要通過接口來與前端對接，對字段之類的,swagger2的出現能夠有效的提示對接效率，降低溝通成本。

swagger2可以在實體，類，方法，參數上添加中文註解，以標註對應的接口、字段、參數等對應的含義。

 

二、項目搭建

       1. 添加依賴:

<dependency>				
  <groupId>io.springfox</groupId>				
  <artifactId>springfox-swagger2</artifactId>				
  <version>2.2.2</version> 
</dependency> 

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

       2.創建配置類

      

@Configuration 
@EnableSwagger2 
public class Swagger2{

	  @Bean
      public Docket createRestApi(){	
		return new Docket(DocumentationType.SWAGGER_2)													 
        .apiInfo(apiInfo())
        .select()																 
        .apis(RequestHandlerSelectors.basePackage("com.example.swagger"))																 
        .paths(PathSelectors.any())																 
        .build();				
       }
				
      private ApiInfo apiInfo()	{	
			return new ApiInfoBuilder()																 
             .title("Spring Boot使⽤Swagger2構建RESTful APIs")																 
             .description("swagger2的api")																 
             .termsOfServiceUrl("url")																 
             .contact("Mr.zhang")																 
             .version("1.0")																 
             .build();			
	}
}

  添加@Configuration註解讓spring來管理改配置類，添加@EnableSwagger2來啓用Swagger。

 實體:

package com.hand.hcf.app.workflow.domain;

import com.baomidou.mybatisplus.annotations.TableField;
import com.baomidou.mybatisplus.annotations.TableName;
import com.hand.hcf.core.domain.Domain;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.time.ZonedDateTime;

/**
 * WorkflowBackReportDTO
 *
 * @Auther: zhengbing.zhang
 * @Date:2020/6/19
 * @remark
 */

@Data
@TableName("workflow_back_report")
public class WorkflowBackReport extends Domain {


    @ApiModelProperty(value = "document_id")
    private Long documentId;

    @ApiModelProperty(value = "單據類型id")
    @TableField("document_type_id")
    private Long documentTypeId;

    @ApiModelProperty(value = "單據大類")
    @TableField("document_type_category")
    private Integer documentTypeCategory;



    @ApiModelProperty(value = "單據類型名稱")
    @TableField("document_type_name")
    private String documentTypeName;

    @ApiModelProperty(value = "單號")
    @TableField("document_number")
    private String documentNumber;

    @ApiModelProperty(value = "公司id")
    @TableField("company_id")
    private Long companyId;

    @ApiModelProperty(value = "公司名稱")
    @TableField("company_name")
    private String companyName;

    @ApiModelProperty(value = "申請人id")
    @TableField("applicant_id")
    private Long applicantId;


    @ApiModelProperty(value = "申請人姓名")
    @TableField("applicant_name")
    private String applicantName;

    @ApiModelProperty(value = "申請人公司id")
    @TableField("applicant_company_id")
    private Long applicantCompanyId;

    @ApiModelProperty(value = "申請人公司名稱")
    @TableField("applicant_company_name")
    private String applicantCompanyName;

    @ApiModelProperty(value = "申請人部門oid")
    @TableField("applicant_deparment_oid")
    private String applicantDeparmentOid;

    @ApiModelProperty(value = "申請人部門名稱")
    @TableField("applicant_deparment_name")
    private String applicantDeparmentName;

    @ApiModelProperty(value = "審批通過日期")
    @TableField("pass_time_date")
    private ZonedDateTime passTimeDate;

    @ApiModelProperty(value = "審批通過日期")
    @TableField("pass_time_str")
    private String passTimeStr;


    @ApiModelProperty(value = "退回次數")
    @TableField("back_counts")
    private Integer backCounts;

    @ApiModelProperty(value = "退回節點類型,區分財務和非財務")
    @TableField("node_types")
    private String nodeTypes;

    @ApiModelProperty(value = "退回節點")
    @TableField("back_nodes")
    private String backNodes;

    @ApiModelProperty(value = "退回原因")
    @TableField("back_reason")
    private String backReason;

    @ApiModelProperty(value = "退回日期")
    @TableField("back_date")
    private ZonedDateTime backDate;

    @ApiModelProperty(value = "退回日期")
    @TableField(exist = false)
    private String backDateStr;
}

 

類和方法:

package com.hand.hcf.app.workflow.web;

import com.baomidou.mybatisplus.plugins.Page;
import com.hand.hcf.app.workflow.domain.WorkflowBackReport;
import com.hand.hcf.app.workflow.dto.WorkflowBackTotalReportDTO;
import com.hand.hcf.app.workflow.service.WorkflowBackReportService;
import com.hand.hcf.core.util.PageUtil;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.data.domain.Pageable;

import java.time.ZonedDateTime;
import java.util.List;

/**
 * WorkflowBackReportController
 *
 * @Auther: zhengbing.zhang
 * @Date:2020/6/19
 * @remark
 */
@RestController
@RequestMapping("/api")
@Api("審批退回數據查詢")
public class WorkflowBackReportController {


    @Autowired
    private WorkflowBackReportService workflowBackReportService;



    @GetMapping("/query/all/back/report")
    @ApiOperation(value = "審批退回報表彙總查詢",notes = "開發: ")
    public ResponseEntity<List<WorkflowBackTotalReportDTO>> queryAllBackReport(
            @ApiParam(value = "公司id") @RequestParam(value = "companyIds",required = false)List<Long> companyIds,
            @ApiParam(value = "申請人公司id") @RequestParam(value = "applicantCompanyId",required = false)Long applicantCompanyId,
            @ApiParam(value = "申請人部門id") @RequestParam(value = "applicantDepartmentId",required = false)Long applicantDepartmentId,
            @ApiParam(value = "單號") @RequestParam(value = "documentNumber",required = false)String documentNumber,
            @ApiParam(value = "報賬單單據類型Id") @RequestParam(value = "documentTypeIds",required = false)List<Long>  documentTypeIds,
            @ApiParam(value = "預付款單據類型id") @RequestParam(value = "CshTypeIds",required = false)List<Long> CshTypeIds,
            @ApiParam(value = "審批通過日期從") @RequestParam(value = "passTimeFrom",required = false) ZonedDateTime passTimeFrom,
            @ApiParam(value = "審批通過日期日期至") @RequestParam(value = "passTimeTo",required = false)ZonedDateTime passTimeTo,
            Pageable pageable){
        Page page = PageUtil.getPage(pageable);
        HttpHeaders totalHeader = PageUtil.getTotalHeader(page);
        List<WorkflowBackTotalReportDTO> lists=workflowBackReportService.queryAllBackReport(
                companyIds,
                applicantCompanyId,
                applicantDepartmentId,
                documentNumber,
                documentTypeIds,
                CshTypeIds,
                passTimeFrom,
                passTimeTo,
                page);
        return new ResponseEntity<>(lists,totalHeader, HttpStatus.OK);
    }

    @GetMapping("/query/back/report/by/companyId")
    @ApiOperation(value = "審批退回報表明細查詢,根據公司id來查詢",notes = "開發:")
    public ResponseEntity<List<WorkflowBackReport>> queryBackReportByCompanyId(
            @ApiParam(value = "公司ID") @RequestParam(value = "companyId") Long companyId,
            Pageable pageable){
        Page page = PageUtil.getPage(pageable);
        HttpHeaders totalHeader = PageUtil.getTotalHeader(page);
        List<WorkflowBackReport> lists=workflowBackReportService.queryBackReportByCompanyId(companyId,page);
        return new ResponseEntity<>(lists,totalHeader, HttpStatus.OK);
    }

}

 

三、訪問swagger

       項目啓動後，比如，默認端口號爲:8080,可以直接在瀏覽器的地址欄裏訪問swagger:  http://localhost:8080/swagger-ui.html

 

方法: