项目配置Swagger2生成API接口文档

逃离我推掉我的手 2022-11-20 09:38 222阅读 0赞

一、Swagger2介绍  
前后端分离开发模式中，api文档是最好的沟通方式。  
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。  
及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)  
规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)  
一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)  
可测性 (直接在接口文档上进行测试，以方便理解业务)

二、配置Swagger2  
1、创建common模块  
在guli-parent下创建模块common  
配置：

groupId：com.atguigu

artifactId：common

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3Noa3N0YXJ0_size_16_color_FFFFFF_t_70_pic_center]  
2、在common中引入相关依赖

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <scope>provided </scope>
            </dependency>

3、在common下面创建子模块service-base，然后在模块service-base中，创建swagger的配置类  
创建包com.atguigu.servicebase.config，创建类SwaggerConfig

@Configuration
    @EnableSwagger2
    public class SwaggerConfig { 
    
        @Bean
        public Docket webApiConfig(){ 
    
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("webApi")
                    .apiInfo(webApiInfo())
                    .select()
                    .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                    .paths(Predicates.not(PathSelectors.regex("/error.*")))
                    .build();
    
        }
        
        private ApiInfo webApiInfo(){ 
    
            return new ApiInfoBuilder()
                    .title("网站-课程中心API文档")
                    .description("本文档描述了课程中心微服务接口定义")
                    .version("1.0")
                    .contact(new Contact("guigu", "http://atguigu.com", "abc@qq.com"))
                    .build();
        }
    }

4、在模块service模块中引入service-base

<dependency>
        <groupId>com.atguigu</groupId>
        <artifactId>service-base</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </dependency>

5、在service-edu启动类上添加注解，进行测试  
![在这里插入图片描述][20201028105234790.png_pic_center]

6、API模型  
可以添加一些自定义设置，例如：  
定义样例数据

@ApiModelProperty(value = "创建时间", example = "2019-01-01 8:00:00")
    @TableField(fill = FieldFill.INSERT)
    private Date gmtCreate;
    
    @ApiModelProperty(value = "更新时间", example = "2019-01-01 8:00:00")
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private Date gmtModified;

7、定义接口说明和参数说明  
定义在类上：@Api  
定义在方法上：@ApiOperation  
定义在参数上：@ApiParam

@Api(description="讲师管理")
    @RestController
    @RequestMapping("/admin/edu/teacher")
    public class TeacherAdminController { 
    
    	@Autowired
    	private TeacherService teacherService;
    
    	@ApiOperation(value = "所有讲师列表")
    	@GetMapping
    	public List<Teacher> list(){ 
    		return teacherService.list(null);
    	}
    
    	@ApiOperation(value = "根据ID删除讲师")
    	@DeleteMapping("{id}")
    	public boolean removeById(
    			@ApiParam(name = "id", value = "讲师ID", required = true)
    			@PathVariable String id){ 
    		return teacherService.removeById(id);
    	}
    }

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3Noa3N0YXJ0_size_16_color_FFFFFF_t_70_pic_center]: /images/20221120/05c68dd14e5043d7ac9f2b2c89abe924.png
[20201028105234790.png_pic_center]: /images/20221120/8e67c040dd644bc8a2e0de9768c86551.png