快捷導(dǎo)航

教你利用springboot集成swagger并生成接口文檔

更新時(shí)間：2021年05月26日 15:06:52 作者：185的阿平

有很多小伙伴不會(huì)利用springboot集成swagger并生成接口文檔,今天特地整理了這篇文章,文中有非常詳細(xì)的代碼圖文介紹及代碼示例,對(duì)不會(huì)這個(gè)方法的小伙伴們很有幫助,需要的朋友可以參考下

效果圖

實(shí)現(xiàn)步驟

1.maven中引入jar包，不同版本的swagger可能頁(yè)面效果不一樣。

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

2.啟動(dòng)類(lèi)加上@EnableSwagger2注解，并在同路徑下創(chuàng)建全局配置類(lèi)。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMethod;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
 
import java.util.ArrayList;
import java.util.List;
 
@Configuration
public class Swagger2Config {
 
 
    @Bean
    public Docket createRestApi() {
        //這塊是定義全局返回碼
        List<ResponseMessage> responseMessageList = new ArrayList<>();
        responseMessageList.add(new ResponseMessageBuilder().code(404).message("找不到資源").build());
        responseMessageList.add(new ResponseMessageBuilder().code(409).message("業(yè)務(wù)邏輯異常").build());
        responseMessageList.add(new ResponseMessageBuilder().code(400).message("網(wǎng)絡(luò)協(xié)議錯(cuò)誤").build());
        responseMessageList.add(new ResponseMessageBuilder().code(500).message("服務(wù)器內(nèi)部錯(cuò)誤--->Exception").build());
        responseMessageList.add(new ResponseMessageBuilder().code(502).message("nginx異常").build());
        return new Docket(DocumentationType.SWAGGER_2).globalResponseMessage(RequestMethod.GET, responseMessageList)
                .globalResponseMessage(RequestMethod.POST, responseMessageList)
                .globalResponseMessage(RequestMethod.PUT, responseMessageList)
                .globalResponseMessage(RequestMethod.DELETE, responseMessageList)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("order.controller"))//包的根路徑
                .paths(PathSelectors.any())
                .build();
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("ORDER-PROVIDER")//接口文檔標(biāo)題設(shè)置
                .description("API接口列表")//描述
                .version("1.0")//版本號(hào)
                .build();
    }
}

3.在相應(yīng)的controller層寫(xiě)對(duì)應(yīng)注解。一般來(lái)說(shuō)接口文檔關(guān)注的幾點(diǎn)，網(wǎng)絡(luò)協(xié)議，接口入?yún)?，接口出參，方法?lèi)型。拿一個(gè)conteller舉例。分幾步：

（1）對(duì)整個(gè)controller類(lèi)加上@Api注解標(biāo)識(shí)為一個(gè)swagger管理的類(lèi)。

（2）方法修飾，加上@ApiOperation對(duì)方法進(jìn)行說(shuō)明。主要參數(shù)如圖

（3）入?yún)⑿揎?。使用@ApiImplicitParams和@ApiImplicitParam一起封裝。如果入?yún)?shù)含有實(shí)體對(duì)象，其中@ApiImplicitParam的name屬性就定義為類(lèi)的類(lèi)型，這樣才能展示。如果為基本類(lèi)型，name即為屬性名稱(chēng)。

（4）出參修飾。可以使用@ApiResponses和@ApiResponse一起封裝。如果返回中含有泛型實(shí)體(目前來(lái)說(shuō)接口返回都是一個(gè)基本返回對(duì)象包裝實(shí)例數(shù)據(jù)對(duì)象)。此時(shí)想要展現(xiàn)出來(lái)，就需要在接口方法處指定返回的泛型，然后在@ApiResponse注解中不要使用Response屬性指定返回類(lèi)型。

@RestController
@RequestMapping("/manager/blacklist")
@Api("黑名單管理")
public class BlackListController{
    @Autowired
    private BlackListService blackListService;
 
    /**
     * 分頁(yè)列表
     */
    @ApiOperation(value = "list",notes = "分頁(yè)列表查詢(xún)",httpMethod = "POST")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query",name = "BlackListDto",value = "黑名單實(shí)體",required = true)
            @ApiImplicitParam(paramType = "query",name = "tokenId",value = "鑒權(quán)Id",required = true)
    })
    @ApiResponses({
            @ApiResponse(code = 200,message = "成功" ),
            @ApiResponse(code= 500,message = "服務(wù)錯(cuò)誤")
    })
    @PostMapping("/list")
    public ResponeModel<BlackListDto> list(@RequestBody BlackListDto blackListDto,String tokenId){
        PageInfo<BlackListDto> list = blackListService.pageList(blackListDto);
        return ResponeModel.ok(list);
    }
}

（5）實(shí)體修飾。要想在swagger界面展現(xiàn)出每個(gè)字段對(duì)應(yīng)的說(shuō)明。最后還需要在實(shí)體類(lèi)中定義一層。使用@ApiModel定義類(lèi)和@ApiModelProperty定義屬性。

import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiParam;
import lombok.Data;
 
import java.util.Date;
 
/**
 * 黑名單表
 * 
 * @email ${email}
 * @date 2021-05-13 14:24:39
 */
@Data
@ApiModel(value = "BlackListDto",description = "黑名單實(shí)體信息")
public class BlackListDto  {
	private static final long serialVersionUID = 1L;
 
	/**
	 * 主鍵id
	 */
	@ApiModelProperty(value = "主鍵ID",name = "id")
	private Long id;
	/**
	 * 買(mǎi)家編號(hào)
	 */
	@ApiModelProperty(value = "買(mǎi)家編號(hào)",name = "buyerNo")
	private String buyerNo;
	/**
	 * 備注，進(jìn)入黑名單的原因
	 */
	@ApiModelProperty(value = "備注",name = "remarks")
	private String remarks;
	/**
	 * 黑名單狀態(tài)：1未恢復(fù)  2已恢復(fù)
	 */
	@ApiModelProperty(value = "黑名單狀態(tài)",dataType = "Integer")
	private Integer status;
	/**
	 * 字符型保留字段1.
	 */
	@ApiModelProperty(value = "字符型保留字段1",name = "fldS1")
	private String fldS1;
	/**
	 * 字符型保留字段2.
	 */
	@ApiModelProperty(value = "字符型保留字段2",name = "fldS2")
	private String fldS2;
	/**
	 * 字符型保留字段3.
	 */
	@ApiModelProperty(value = "字符型保留字段3",name = "fldS3")
	private String fldS3;
	/**
	 * 數(shù)值型保留字段
	 */
	@ApiModelProperty(value = "數(shù)值型保留字段1",name = "fldN1")
	private Integer fldN1;
	/**
	 * 數(shù)值型保留字段
	 */
	@ApiModelProperty(value = "數(shù)值型保留字段2",name = "fldN2")
	private Integer fldN2;
	/**
	 * 創(chuàng)建時(shí)間
	 */
	@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss",timezone = "GMT+8",locale = "zh")
	@ApiModelProperty(value = "創(chuàng)建時(shí)間",name = "createDate")
	private Date createDate;
	/**
	 * 修改人
	 */
	@ApiModelProperty(value = "修改人",name = "updateBy")
	private String updateBy;
	/**
	 * 修改時(shí)間
	 */
	@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss",timezone = "GMT+8",locale = "zh")
	@ApiModelProperty(value = "修改時(shí)間",name = "updateDate")
	private Date updateDate;
	/**
	 * 創(chuàng)建人ID
	 */
	@ApiModelProperty(value = "創(chuàng)建人",name = "createBy")
	private String createBy;
}

到此這篇關(guān)于教你利用springboot集成swagger并生成接口文檔的文章就介紹到這了,更多相關(guān)springboot集成swagger內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: