java SpringBoot（二十）SpringBoot Swagger自动生成API接口文档

水深无声 2022-10-06 01:50 290阅读 0赞

**什么是Swagger：**

Swagger是一款Restful接口的文档在线自动生成和功能测试功能软件。  
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

**pom中导入依赖：**

<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>

**增加自动配置：**

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwNzcxNTY3_size_16_color_FFFFFF_t_70][]

package com.zr.mall.demo.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.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    public class Swagger2Config {
    
        /**
         1. swagger配置类
         */
        @Configuration
        @EnableSwagger2
        public class SwaggerConfig {
            @Bean
            public Docket createRestApi() {
                return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo())
                        //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                        //.enable(true)
                        .select()
                        //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                        .apis(RequestHandlerSelectors.basePackage("com.zr.mall.demo.controller"))
                        //指定路径处理PathSelectors.any()代表所有的路径
                        .paths(PathSelectors.any())
                        .build();
            }
    
            private ApiInfo apiInfo() {
                return new ApiInfoBuilder()
                        //设置文档标题(API名称)
                        .title("SpringBoot中使用Swagger2接口规范")
                        //文档描述
                        .description("接口说明")
                        //服务条款URL
                        .termsOfServiceUrl("http://localhost:8080/")
                        //版本号
                        .version("1.0.0")
                        .build();
            }
        }
    
    }

**Controller中测试使用：**

**@Api开头的注解一般是用Swagger来描述接口的**

package com.zr.mall.demo.controller;
    
    import com.zr.mall.demo.common.api.CommonResult;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.stereotype.Controller;
    import org.springframework.web.bind.annotation.*;
    
    //接口文件描述
    @Api(value = "API大全", tags = "MallController", description = "商品api")
    @Controller
    @RequestMapping("/mall")
    public class MallController {
    
        @ApiOperation(value = "测试返回成功", notes = "测试返回成功2")
        @RequestMapping(value = "/testSuccess", method = RequestMethod.GET)
        @ResponseBody
        public CommonResult  returnSuccess(){
            return CommonResult.success("test");
        }
    
        //接口功能描述 notes：实施说明
        @ApiOperation(value = "测试Swagger", notes = "测试Swagger2")
        //name：参数名 value：参数说明 dataType：参数类型 required：是否必须 defaultValue：默认值
        @ApiImplicitParam(name="name",value = "name的值",dataType = "String",required = false,defaultValue = "aaa")
        @RequestMapping(value = "/swag/{id}", method = RequestMethod.GET)
        @ResponseBody
        public CommonResult testSwagger(@PathVariable("id")Long id, @RequestParam(value = "name",defaultValue = "aaa") String name){
            return CommonResult.success(id+name);
        }
    
    }

**启动 访问接口文档：**

[http://localhost:8080/swagger-ui.html\#!/MallController/testSwaggerUsingGET][http_localhost_8080_swagger-ui.html_MallController_testSwaggerUsingGET]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwNzcxNTY3_size_16_color_FFFFFF_t_70 1][]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwNzcxNTY3_size_16_color_FFFFFF_t_70]: /images/20221005/1d50f3c911d44e97871f87e8bb6c1e5f.png
[http_localhost_8080_swagger-ui.html_MallController_testSwaggerUsingGET]: http://localhost:8080/swagger-ui.html#!/MallController/testSwaggerUsingGET
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwNzcxNTY3_size_16_color_FFFFFF_t_70 1]: /images/20221005/4597a4e359b34841817459d69e06cb0f.png