SpringBoot整合Swagger2生成接口文档

青旅半醒 2022-12-03 09:08 339阅读 0赞

### 文章目录 ###

*   *  一、导入依赖
     *  二、配置Swagger类
     *  三、启动访问
     *  四、Swagger2注解详解
     *  五、把Swagger2的API接口导入Postman

## 一、导入依赖 ##

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.8.0</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.8.0</version>
            </dependency>

## 二、配置Swagger类 ##

import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
    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;
    
    /** * 整合swagger2 */
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig extends WebMvcConfigurationSupport { 
    
        /** * 设置一个开关，生产版本为false，关闭swagger */
        @Value("${swagger.enable}")
        private boolean enable;
    
        @Bean
        public Docket createRestApi() { 
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).
                    enable(enable).select()
                    //为当前包下controller生成API文档
    // .apis(RequestHandlerSelectors.basePackage("com.tt.demo.controller"))
                    //为有@Api注解的Controller生成API文档
    // .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                    //为有@ApiOperation注解的方法生成API文档
    // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    //为任何接口生成API文档
                    .apis(RequestHandlerSelectors.any())
                    .paths(PathSelectors.any()).build();
    
    
            //可以设置为扫描多个包
            /** * com.google.common.base.Predicate<RequestHandler> selector1 = RequestHandlerSelectors.basePackage("设置你要扫描的包路径"); * com.google.common.base.Predicate<RequestHandler> selector2 = RequestHandlerSelectors.basePackage("设置你要扫描的包路径"); * createRestApi这样写即可。 * @Bean * public Docket createRestApi(){ * return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()). * enable(ebable).select(). * apis(Predicates.or(selector1,selector2)). * paths(PathSelectors.any()).build(); * } */
        }
    
    
        @SuppressWarnings("deprecation")
        public ApiInfo apiInfo() { 
            return new ApiInfoBuilder().title("接口文档").
                    description("服务端通用接口").version("1.0").build();
        }
    
        /** * 一定要写这个方法，不然访问swagger-ui.html页面会404 * * @param registry */
        @Override
        protected void addResourceHandlers(ResourceHandlerRegistry registry) { 
            registry.addResourceHandler("/**").
                    addResourceLocations("classpath:/META-INF/resources/").
                    setCachePeriod(0);
        }
    
    }

SwaggerConfig类上有一个ebable属性，我们可以在yml文件上定义一下，当我们要上生产环境时，把这个ebable属性为false，swagger就关闭了。

swagger: ##给swagger设置一个开关
      enable: true

配置好了，咱们来写一个controller。

import com.tt.demo.model.User;
    import io.swagger.annotations.*;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.PathVariable;
    import org.springframework.web.bind.annotation.RestController;
    
    @RestController
    @Api(description = "用户模块", value = "用户接口")  //使用@Api来修饰类
    public class UserController { 
    
    
        @GetMapping("/getUser/{age}")
        //使用@ApiOperation注解来修饰接口
        @ApiOperation(value = "通过用户Id来获取用户信息", notes = "RestFul风格，需要传用户Id")
        //使用ApiImplcitParam修饰接口参数
        @ApiImplicitParams({ @ApiImplicitParam(name = "age", value = "用户年龄", required = true),
                @ApiImplicitParam(name = "name", value = "用户名称", required = true),
                @ApiImplicitParam(name = "id", value = "用户Id", required = false)})
        public User getUserById(@PathVariable("age") Integer age, String name, String id) { 
            return new User(id, name, age);
        }
    }

## 三、启动访问 ##

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjc0MDUzMA_size_16_color_FFFFFF_t_70_pic_center]  
启动成功后，直接访问`localhost:8080/swagger-ui.html`，就能看到swagger为咱们生成的接口文档了。

## 四、Swagger2注解详解 ##

@Api：修饰整个类，描述Controller的作用
    @ApiOperation：描述一个类的一个方法，或者说一个接
    @ApiParam：单个参数描述
    @ApiModel：用对象来接收参数
    @ApiProperty：用对象接收参数时，描述对象的一个字段
    @ApiResponse：HTTP响应其中1个描述
    @ApiResponses：HTTP响应整体描述
    @ApiIgnore：使用该注解忽略这个API
    @ApiError ：发生错误返回的信息
    @ApiImplicitParam：一个请求参数
    @ApiImplicitParams：多个请求参数

**1、@Api ：请求类的说明**

@Api：放在请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
        tags="说明该类的作用"
        value="该参数没什么意义，所以不需要配置"

举例：

@Api(tags = "账户相关模块")
    @RestController
    @RequestMapping("/api/account")
    public class AccountController { 
        //TODO
    }

**2、@ApiOperation：方法的说明**

@ApiOperation："用在请求的方法上，说明方法的作用"
        value="说明方法的作用"
        notes="方法的备注说明"

举例：

@ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
    @PostMapping("/changepass")
    public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
            @RequestBody @Valid PasswordModel passwordModel) { 
        //TODO
    }

**3、@ApiImplicitParams、@ApiImplicitParam：方法参数的说明**

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
        @ApiImplicitParam：对单个参数的说明      
            name：参数名
            value：参数的汉字说明、解释
            required：参数是否必须传
            paramType：参数放在哪个地方
                · header --> 请求参数的获取：@RequestHeader
                · query --> 请求参数的获取：@RequestParam
                · path（用于restful接口）--> 请求参数的获取：@PathVariable
                · body（请求体）-->  @RequestBody User user
                · form（普通表单提交）     
            dataType：参数类型，默认String，其它值dataType="int"       
            defaultValue：参数的默认值

举例：

@ApiOperation(value="用户登录",notes="随边说点啥")
    @ApiImplicitParams({ 
            @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
            @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
            @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
    })
    @PostMapping("/login")
    public AjaxResult login(@RequestParam String mobile, @RequestParam String password,
                            @RequestParam Integer age){ 
        //TODO
        return AjaxResult.OK();
    }

**单个参数举例**

@ApiOperation("根据部门Id删除")
    @ApiImplicitParam(name="depId",value="部门id",required=true,paramType="query")
    @GetMapping("/delete")
    public AjaxResult delete(String depId) { 
        //TODO
    }

**4、@ApiResponses、@ApiResponse：方法返回值的说明**

@ApiResponses：方法返回对象的说明
        @ApiResponse：每个参数的说明
            code：数字，例如400
            message：信息，例如"请求参数没填好"
            response：抛出异常的类

举例：

@ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
    @ApiResponses({ 
            @ApiResponse(code = 400, message = "请求参数没填好"),
            @ApiResponse(code = 404, message = "请求路径找不到")
    })
    @PostMapping("/changepass")
    public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
            @RequestBody @Valid PasswordModel passwordModel) { 
        //TODO
    }

**5、@ApiModel：用于JavaBean上面，表示一个JavaBean**

@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息
        （这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 ）

**6. @ApiModelProperty：用在JavaBean的属性上面，说明属性的含义**

@ApiModel和 @ApiModelProperty举例：
    @ApiModel("修改密码所需参数封装类")
    public class PasswordModel
    { 
        @ApiModelProperty("账户Id")
        private String accountId;
    //TODO
    }

## 五、把Swagger2的API接口导入Postman ##

1、访问`http://localhost:8080/swagger-ui.html` 文档的首页，复制下面这个地址  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjc0MDUzMA_size_16_color_FFFFFF_t_70_pic_center 1]  
2.打开postman–>import–>import Form Link

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjc0MDUzMA_size_16_color_FFFFFF_t_70_pic_center 2]

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjc0MDUzMA_size_16_color_FFFFFF_t_70_pic_center 3]

参考链接：  
https://www.jianshu.com/p/77eb86bb3faa  
https://zhuanlan.zhihu.com/p/98075551

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjc0MDUzMA_size_16_color_FFFFFF_t_70_pic_center]: /images/20221123/9f4521d1db324dee8bfde0bb686b78d4.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjc0MDUzMA_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20221123/75387f433f32403882ff3d5f582ab528.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjc0MDUzMA_size_16_color_FFFFFF_t_70_pic_center 2]: /images/20221123/41c6822283434530adde0526508d6f3c.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjc0MDUzMA_size_16_color_FFFFFF_t_70_pic_center 3]: /images/20221123/0d014b71308b4633bd0a437279611278.png