spring boot ＋Swagger-ui 编写后台接口文档

什么是Swagger

Swagger是一个Restful风格接口的文档在线自动生成和测试的框架

springboot 集成 swagger -ui

1、添加Swagger2的Maven依赖

<!-- Swagger API文档 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2、创建Swagger2配置类

import io.swagger.annotations.ApiOperation;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2
public class Swagger2Config {

    /**
     * swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
     *
     * @return Docket
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //此包路径下的类，才生成接口文档
                .apis(RequestHandlerSelectors.basePackage("com.swd.imes.web"))
                //加了ApiOperation注解的类，才生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }


    /**
     * api文档的详细信息函数,注意这里的注解引用的是哪个
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // //大标题
                .title("XXX系统接口")
                // 版本号
                .version("1.0")
//                .termsOfServiceUrl("NO terms of service")
                // 描述
                .description("后台服务API接口文档")
                // 作者
                .contact("程序猿  XXX ")
                 // .contact(new Contact("admin", " ", " "))
                // .license("The Apache License, Version 2.0")
                //.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }

}

@Configuration注解，让Spring来加载该类配置
@EnableSwagger2注解 启用Swagger2
createRestApi()函数创建Docket的Bean
        select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现
        本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
apiInfo()函数创建该Api的基本信息（这些基本信息会展现在文档页面中）。

3、添加文档内容

@RestController
@RequestMapping("/ifactory/swd/http/pack")
@Api("设备集成接口")
public class DeviceIntegratedInterface {

    @Resource
    ILoginService iLoginService;

    @ApiOperation(value = "登录接口", notes = "接口返回数据格式为{\"STATUS\":\"true\",\"RESULT\":\"JSESSION标识\"}如果登录成功返回“true”和” JSESSION标识”，JESSION标识需要保存为全局变量，每次登录之后都要更新全局变量的值。")
    @PostMapping("/equipmentIntegratedAction!logIn.action")
    public Result login(
            @ApiParam(value = "站点", required = true) @RequestParam(value = "siteId", required = true) String siteId,
            @ApiParam(value = "用户", required = true) @RequestParam(value = "Username", required = true) String username,
            @ApiParam(value = "密码", required = true) @RequestParam(value = "Password", required = true) String password,
            @ApiParam(value = "工序", required = true) @RequestParam(value = "OPERATION", required = true) String operation,
            @ApiParam(value = "资源", required = true) @RequestParam(value = "RESOURCE", required = true) String resource,
            HttpServletRequest request) {

        if (StringUtils.isBlank(username)) {
            throw new ServiceException("用户名不能为 空！");
        }
        if (StringUtils.isBlank(password)) {
            throw new ServiceException("密码不能为 空！");
        }
        if (StringUtils.isBlank(siteId)) {
            throw new ServiceException("站点不能为 空！");
        }

        LoginVo loginDto = new LoginVo().setSiteId(siteId).setUsername(username).setPassword(password)
                .setOperation(operation).setResource(resource).setBaseUrl(CommonUtils.getBaseUrl(request))
                .setAccessUrl(CommonUtils.getIpAddress(request));
        return ResultGenerator.genSuccessResult(iLoginService.login(loginDto));
    }

    @Resource
    ICheckOperationService iCheckOperationService;

    @ApiOperation(value = "检查是否在当前工序上排队")
    @PostMapping("/equipmentIntegratedAction!doCheckOperation.action")
    public Result doCheckOperation(
            @ApiParam(value = "json", required = true) @RequestParam(value = "dataJson") String dataJson) {

        CheckOperationVo checkOperationVo = JSON.parseObject(dataJson, CheckOperationVo.class);
        return ResultGenerator.genSuccessResult(iCheckOperationService.isCurOperationNew(checkOperationVo));
    }
}

完成上述代码添加上，启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html

在controller上添加注解，自动生成API文档

常用注解：

@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiParam: 用于方法，参数，字段说明，表示对参数的添加元数据（说明或是否必填等）

@RestController
@RequestMapping("/ifactory/swd/http/pack")
@Api("查询接口")
public class QueryDataInterface {

    @Resource
    ICheckBarcodeService iCheckBarcodeService;

    @ApiOperation(value = "电芯条码与PACK条码互查" ,notes="单电芯PackSn和CellSn互查/多电芯任意一个CellSn查PackSn")
    @PostMapping("/equipmentIntegratedAction!doCheckBarcode.action")
    public Result doCheckBarcode(@ApiParam(value = "json", required = true) @RequestParam(value = "dataJson") String dataJsonVo) {
        CheckBarcodeVo checkBarcodeVo = JSON.parseObject(dataJsonVo, CheckBarcodeVo.class);
        return ResultGenerator.genSuccessResult(iCheckBarcodeService.findCellCode(checkBarcodeVo));
    }
}

 

@ApiOperation和@ApiParam为添加的API相关注解，个参数说明如下： 
@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”）；其他参数可参考源码； 
@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”）

 

https://www.cnblogs.com/woshimrf/p/5863318.html