如何用Swagger 2生成接口文档

男娘i 2022-12-19 11:49 253阅读 0赞

基于springboot + swagger 生成接口文档  
**1.基于springboot环境 添加swagger依赖： 在web模块添加**

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

**2. 定义swagger配置类**

package com.wzl.item.config;
    import com.wzl.item.WzlItemApplication;
    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 SwaggerConfig { 
        @Bean
        public Docket createRestApi() { 
            String basePck = WzlItemApplication.class.getPackage().getName(); // 启动类
            System.out.println(basePck+"=启动类所在的包为路径扫描=====定义生成接口文档的包路径=====");
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage(basePck))
                    .paths(PathSelectors.any())
                    .build();
        }
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("公司名称_项目名称_接口文档")
                    .description("描述内容")
                    .version("1.0.0")
                    .build();
        }
    
    }

**3 .swagger常用注解说明**  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NTA3MTc2Ng_size_16_color_FFFFFF_t_70_pic_center]  
常用两个注解： 一个类上的 和 一个方法 上的

@Api 和 @ApiOperation

在这里插入代码片@Api("公司名称_模块名称_接口文档API")
    @RestController
    public class MyItemController { 
          // 请求方式需要具体定义 add @PostMapping ...
        @DeleteMapping("deleteMyItemById/{id}")
        @ApiOperation(value = "删除模块", notes = "根据id 逻辑删除")
        public Result deleteMyItemById(@PathVariable("id") Integer id){ }
    }

**4 .Rest风格相关注解使用说明**  
一般在controller对象中接收浏览器请求 对于的不同的crud 请求 我们采用不同的注解接收，这样接口文档生成才会规范

@PostMapping：

url的post请求，相当于@RequestMapping(method=RequestMethod.POST)，但只能用在方法上，不能用在类上

@GetMapping：在Restful API中代表 查询

@PutMapping：在Restful API中代表 更新

@DeleteMapping：在Restful API中代表 删除

@GetMapping("/user/\{id\}") 表示给请求url中的/user/后的片段取了个名为id，这个片段在参数中可以用

@PathVariable注解获取路径参数信息

*  PathVariable：路径变量，可以用来做路径传参功能，该功能相对于问号传参更加方便，可以直接指定变量的数据类型，而无需再做数据类型的转换，也可以实现传入多个参数

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NTA3MTc2Ng_size_16_color_FFFFFF_t_70_pic_center]: /images/20221120/4aa72fda51774f31979318e37e10e8da.png