spring boot 集成swagger2

2024-03-23 17:50:04

为了节省写API文档花费的大量时间，我选择使用Swager2作为项目中的API管理工具、也方便维护

      Swagger2的优点

      （一）及时性(接口文档在线自动生成，文档随接口变动实时更新，节省维护成本)

      （二）可测性（支持在线接口测试，不依赖第三方工具）

      （三）规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)

      （四）一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)

1.pom.xml 添加如下 Maven 依赖

<properties>
        <docker.image.prefix>mistra</docker.image.prefix>
        <maven.test.skip>true</maven.test.skip>
        <mybatis-plus.version>3.2.0</mybatis-plus.version>
        <jwt.version>3.8.3</jwt.version>
        <shiro-spring.version>1.4.0</shiro-spring.version>
        <commons-lang3.version>3.9</commons-lang3.version>
 	</properties>
<!-- swagger ui -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${swagger.version}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger.version}</version>
    </dependency>
    <!--增加两个配置(解决swagger访问配置首页报异常问题)-->
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.22</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.5.22</version>
    </dependency>

2.yml中配置swagger

## swagger 配置 -start
swagger:
  version: v1
  groupName: 设置Json文档格式名称
  title: 设置文档标题
  description: 设置文档描述
  # 扫描的包路径
  basePackage: com.szylt.projects
## swagger 配置 -end

3.在项目中创建SwaggerInfo.java

/**
 * @author zhangpeng
 * @date 2020/11/6 14:08
 * Utils: Intellij Idea
 * Description: swagger 配置信息
 */
@Data
@Component
@ConfigurationProperties(prefix = "swagger")
public class SwaggerInfo {

    /**
     * 标题
     */
    private String title;

    /**
     * 简介
     */
    private String description;

    /**
     * json文档格式名称
     */
    private String groupName;

    /**
     * 版本
     */
    private String version;

    /**
     * 扫描的包路径
     */
    private String basePackage;

    /**
     * 接口作者
     */
    private String author;
}

4.在创建SwaggerConfiguration.java

/**
 * @author zhangpeng
 * @date 2020/11/6 14:07
 * Utils: Intellij Idea
 * Description: swagger配置类
 */
@Configuration
@EnableSwagger2//开启Swagger
@AllArgsConstructor
@Profile({"dev", "test"})//只在测试环境可访问，生产环境不可访问。
@EnableConfigurationProperties(SwaggerInfo.class)
public class SwaggerConfiguration {

    private SwaggerInfo swaggerInfo;

    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return 摘要信息
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(swaggerInfo.getGroupName())//返回json格式文档
                .useDefaultResponseMessages(false)
                .enableUrlTemplating(false)
                .forCodeGeneration(true)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerInfo.getBasePackage()))
                .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中)
     *访问地址：http://项目实际地址/swagger-ui.html
     * @return 返回ApiInfo
     */
    private ApiInfo apiInfo() {
	// 两种方式实现APIinfo:
	// 1.new ApiInfo()：有参构造函数初始化方式可以对文档菜单扩展
//        StringVendorExtension vendorExtension = new StringVendorExtension("hrf", "");
//        Collection<VendorExtension> vendorExtensions = new ArrayList<>();
//        vendorExtensions.add(vendorExtension);
//        Contact contact = new Contact("hrf", "http://192.168.1.20:8001/swagger/ui/index", "526895273@qq.com");
//        return new ApiInfo(
//                swaggerInfo.getTitle(),
//                swaggerInfo.getDescription(),
//                swaggerInfo.getVersion(),
//                "http://192.168.1.20:8001/swagger/ui/index", contact, "hrf", "hrf",
//                vendorExtensions);

	// 2.new ApiInfoBuilder():是以链式编程来实现,目前选择使用第2种方式的比较多
        return new ApiInfoBuilder()
                .title(swaggerInfo.getTitle()) // 设置文档标题
                .description(swaggerInfo.getDescription()) // 设置文档的描述
                .termsOfServiceUrl("https://www.zgylt.com/")// 设置文档的License信息->1.3 License information
                .contact(new Contact("hrf","https://www.zgylt.com/","526895273@qq.com"))
                .version(swaggerInfo.getVersion())// 设置文档的版本信息-> v1 Version information
                .build();
    }
}

5.完成上面配置后及可以开始 API 接口的编写了

/**
 * @author zhangpeng
 * @date 2020/11/6 17:54
 * Utils: Intellij Idea
 * Description: 演示前端控制器
 */
@Slf4j
@RestController
@Api(tags = "demo(演示)")
@AllArgsConstructor
@RequestMapping("/api/demo")
public class DemoController {

    private IDemoService userService;

    /**
     * 演示添加用户
     * @param addDemoForm 表单数据
     * @return 成功或者失败
     */
    @ApiOperation("演示添加用户")
    @PostMapping("/addUser")
    public ResultVo addUser(@ApiParam(value = "演示添加用户表单数据")@Validated @RequestBody AddDemoForm addDemoForm){
        if (userService.addUser(addDemoForm)) {
            return ResultVoUtil.success();
        }else {
            return ResultVoUtil.error(ResultEnum.ADD_ERROR);
        }
    }

    /**
     * 演示获取用户列表
     * @param listDemoForm 表单数据
     * @return 用户列表
     */
    @ApiOperation("演示获取用户列表")
    @ApiImplicitParam(name = "listDemoForm", value = "演示获取详细实体listDemoForm", required = true, dataType = "ListDemoForm")
    @GetMapping("/listUser")
    @ApiResponses(
            @ApiResponse(code = 200,message = "操作成功",response = DemoVo.class)
    )
    public ResultVo listUser(@ApiParam(value = "演示获取用户表单数据")ListDemoForm listDemoForm){
        log.info("UserController.listUser params ==> {}", listDemoForm);
        return ResultVoUtil.success(userService.listUser(listDemoForm));
    }

    /**
     * 演示删除用户
     * @param id 用户编号
     * @return 成功或者失败
     */
    @ApiOperation("演示删除用户")
    @ApiImplicitParam(name = "id", value = "演示用户id", required = true, dataType = "String")
    @DeleteMapping("/deleteUser/{id}")
    public ResultVo deleteUser(@ApiParam(value = "用户编号")@PathVariable("id") String id){
        userService.deleteUser(id);
        return ResultVoUtil.success();
    }
}

6.启动Springboot去页面*问swagger

spring boot 集成swagger2

本案例示例了 @Api,@ApiOperation, @ApiImplicitParam,@ApiResponses,@ApiParam.等注解的使用

Swagger 通过注解定制接口对外展示的信息，这些信息包括接口名、请求方法、参数、返回信息等。

更多注解类型：

(一)@Api：修饰整个类，描述Controller的作用
(二)@ApiOperation：描述一个类的一个方法，或者说一个接口
(三)@ApiParam：单个参数描述
(四)@ApiModel：用对象来接收参数
(五)@ApiProperty：用对象接收参数时，描述对象的一个字段
(六)@ApiResponse：HTTP响应其中1个描述
(七)@ApiResponses：HTTP响应整体描述
(八)@ApiIgnore：使用该注解忽略这个API
(九)@ApiError ：发生错误返回的信息
(十)@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值

 

上一篇：java合并时间段去重


下一篇：SQL 报表 生成月份临时表