SpringBoot整合Swagger

最新推荐文章于 2023-03-23 11:29:56 发布

原创最新推荐文章于 2023-03-23 11:29:56 发布 · 702 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#java #swagger #springboot

Java 专栏收录该内容

46 篇文章

订阅专栏

本文介绍如何使用 Swagger 构建清晰、易于理解的 API 文档。包括添加依赖、配置及使用注解等基本操作，并演示了如何通过自定义请求体参数和返回内容增强文档实用性。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

添加依赖包

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.7.1.RELEASE</version>
</dependency>

开启Swagger

在 *Application 类上面启用注解
```
@EnableSwagger2Doc
```

一般用法（网上后很多资料，这里不再赘述）

@RestController
@RequestMapping("/community")
@Api(value = "/community", description = "小区相关操作")
public class CommunityController {

    private final ResultObject resultObject;

    @Autowired
    public CommunityController(ResultObject resultObject) {this.resultObject = resultObject;}

    @RequestMapping(value = "", method = RequestMethod.DELETE)
    @ApiOperation(value = "删除小区（删除顺序：id、cityId、address）")
    @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "小区编号", dataType = "string"), @ApiImplicitParam(name =
            "cityId", value = "所属城市编号", dataType = "string"), @ApiImplicitParam(name = "address", value = "小区地址",
            dataType = "string")})
    public ResultObject remove(String id, String cityId, String address) {
        return resultObject;
    }

    @RequestMapping(value = "", method = RequestMethod.PUT)
    @ApiOperation(value = "更新小区地址")
    @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "小区编号", dataType = "string", required = true),
            @ApiImplicitParam(name = "cityId", value = "新的城市编号", dataType = "string"), @ApiImplicitParam(name =
            "address", value = "新的小区地址", dataType = "string")})
    public ResultObject update(@RequestParam String id, String cityId, String address) {
        return resultObject;
    }
}

解决实际项目中一般用法遇到的不足（自定义requestBody参数）

定义一个模型类（getter和setter必须要有）

@ApiModel(value = "swaggerModel", description = "Swagger Model Demo")
public class SwaggerModel {

    @ApiModelProperty(value = "编号", required = true)
    private String id;

    @ApiModelProperty(value = "名字", required = true)
    private String name;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

创建一个测试的控制器

@RestController
@RequestMapping("/swagger")
@Api(value = "/swagger", description = "swagger demo")
public class SwaggerController {

    @RequestMapping(value = "", method = RequestMethod.GET)
    @ApiOperation("测试")
    public String test(@RequestBody @ApiParam SwaggerModel swaggerModel) {
        return "200 ok";
    }
}

效果如下：

swagger test

自定义返回内容

定义模型类

public class ResultObject<T> {

    private Integer code;

    private String message;

    private String status;

    private T data;

    ... setter and getter
}

假设有这样一个数据传输对象

/**
 * 这里用到了lombok插件
 **/
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "image", description = "图片信息")
public class ImageVO implements Serializable {

    @ApiModelProperty(value = "图片编号")
    private Long id;

    @ApiModelProperty(value = "图片访问链接")
    private String url;

    @ApiModelProperty(value = "图片标签")
    private String tag;
}

我们还需要写一个Controller接口来测试

@RequestMapping(value = "/upload", method = RequestMethod.POST)
@ApiOperation("上传图片（上传成功会返回图片的URL）")
@ApiImplicitParams({@ApiImplicitParam(name = "image", value = "图片", required = true, dataTypeClass =
        MultipartFile.class), @ApiImplicitParam(name = "tag", value = "图片标签")})
public ResultObject<ImageVO> upload(@RequestBody MultipartFile image, String tag) throws IOException {
    return new ResultObject<>();
}

效果如下：

response