Swagger2配置记录-接口文档

 

 

1、添加依赖到你的项目里

    io.springfox
    springfox-swagger-ui
    2.9.2



    io.springfox
    springfox-swagger2
    2.9.2

 2、添加swagger的系统配置

package com.bingchuan.swagger.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * API文档
 *
 * @author : bingchuan
 * @date : 2020/7/3 9:48
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {


    @Bean
    public Docket createSwaggerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiinfo())
                //选择显示的接口所在的路径
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bingchuan.swagger"))
                .paths(PathSelectors.any())
                .build();

    }

    /**
     * 构建api文档相关信息
     *
     * @return
     */
    private ApiInfo buildApiinfo() {
        return new ApiInfoBuilder()
                .title("标体")
                .version("version")
                .description("描述内容")
                .contact(new Contact("sanshu", "www.bingchuanai.club", "[email protected]"))
                .build();

    }


}

 

 3、控制层添加配置

import com.bingchuan.swagger.dto.DtoEnglishWordRequest;
import com.bingchuan.swagger.dto.DtoResponse;
import com.bingchuan.swagger.service.EnglishWordService;
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.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * 英语单词服务
 *
 * @author : bingchuan
 * @date : 2020/7/1 17:12
 */
@Api(value = "英语单词服务接口", tags = "英语单词服务接口")
@RestController
@RequestMapping(value = "english/word")
public class EnglishWordController {

    private EnglishWordService wordService;

    @Autowired
    public EnglishWordController(EnglishWordService wordService) {
        this.wordService = wordService;
    }

    @PostMapping(value = "add")
    @ApiOperation(value = "添加英语单词接口", notes = "添加英语单词节点")
    public DtoResponse addEnglishWord(
            @ApiParam(value = "DtoEnglishWordRequest", name = "英语单词请求对象", required = true)
            @RequestBody DtoEnglishWordRequest dtoEnglishWordRequest) {
        return wordService.addEnglishWord(dtoEnglishWordRequest);
    }
}

4、请求对象添加配置

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.io.Serializable;

/**
 * @author : bingchuan
 * @date : 2020/7/1 16:54
 */

@Data
@ApiModel(description = "英语单词请求对象")
public class DtoEnglishWordRequest implements Serializable {

    @ApiModelProperty(position = 1, value = "单词编码", example = "name")
    private String wordCode;
    @ApiModelProperty(position = 2, value = "单词类型，词性", example = "n.")
    private String wordType;
    @ApiModelProperty(position = 3, value = "中文含义", example = "姓名")
    private String chineseMean;
    @ApiModelProperty(position = 4, value = "单词例句", example = "My name is SanShu")
    private String wordExample;
    @ApiModelProperty(position = 5, value = "单词描述", example = "我的名字是三树")
    private String wordDescription;


}

 5、响应对象添加配置

import com.bingchuan.swagger.utils.EResultCode;
import io.swagger.annotations.ApiModel;

/**
 * @author Bingchuan
 * @date 2020-03-07
 */

@ApiModel(description = "响应对象")
public class DtoResponse extends DtoResultMessage {


    public DtoResponse(EResultCode resultCode) {
        super(resultCode);
    }

}

import com.bingchuan.swagger.utils.EResultCode;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;

/**
 * @author shanshu
 * @date 20200307
 */
@ApiModel(description = "响应消息结果")
public class DtoResultMessage implements Serializable {

    @ApiModelProperty(value = "响应编码", required = true)
    private String code;

    @ApiModelProperty(value = "响应描述", required = true)
    private String message;

    DtoResultMessage() {

    }

    DtoResultMessage(EResultCode resultCode) {
        this.code = resultCode.getCode();
        this.message = resultCode.getMessage();
    }


    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

6、访问地址：

http://${ip}:${port}/${projectName}/swagger-ui.html

注：可以在swagger接口文档中调用和测试接口的功能。可以给对接方提供接口文档。