Spring Mvc整合Swagger-UI实现在线API文档

迈不过友情╰ 2022-12-28 09:27 171阅读 0赞

## Swagger-UI简介 ##

### Swagger-UI ###

Swagger-UI是HTML, Javascript, CSS的一个集合，可以动态地根据注解生成在线API文档。

### 常用注解 ###

*  @Api：用于修饰Controller类，生成Controller相关文档信息
 *  @ApiOperation：用于修饰Controller类中的方法，生成接口方法相关文档信息
 *  @ApiParam：用于修饰接口中的参数，生成接口参数相关文档信息
 *  @ApiModelProperty：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息
 *  @ApiIgnore：屏蔽接口，加在方法上面屏蔽单个，加在类上面屏蔽整个类

## 整合Swagger-UI ##

### 添加依赖 ###

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

### 在spring-mvc.xml中添加配置 ###

<context:component-scan base-package="包名"></context:component-scan>
    
    <bean class="包名.SwaggerConfig" />
    <mvc:default-servlet-handler />

### 创建Swagger配置类 ###

package com.sqtg.swagger;
    
    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.WebMvcConfigurerAdapter;
    
    import com.google.common.base.Predicates;
    
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import io.swagger.annotations.ApiOperation;
    
    //@Configuration表示是配置文件 从Spring3.0，@Configuration用于定义配置类，可替换xml配置文件，被注解的类内部包含有一个或多个被@Bean注解的方法，这些方法将会被AnnotationConfigApplicationContext或AnnotationConfigWebApplicationContext类进行扫描，并用于构建bean定义，初始化Spring容器。
    @Configuration
    //开启这个配置
    @EnableSwagger2
    public class SwaggerConfig extends WebMvcConfigurerAdapter { 
        /** * @Description:swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等，注：让我们的swagger2扫描我们controller */
        @Bean
        public Docket createRestApi() { 
            /* return new Docket(DocumentationType.SWAGGER_2).select() .apis(Predicates.not(RequestHandlerSelectors.basePackage("org.springframework.boot"))) .build(); */
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                    //为当前包下controller生成API文档
                    .apis(RequestHandlerSelectors.basePackage("com.sqtg.web"))
                    //为有@ApiOperation注解的方法生成API文档，默认为包下所有方法生成API文档
                    //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
                    .build();
        }
        /* @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); } */
    
        /** * @Description: 构建 api文档的信息 */
    	private ApiInfo apiInfo() { 
    		return new ApiInfoBuilder()
    				// 设置页面标题
    				.title("xxxx接口文档")
    				// 设置联系人
    				.contact(new Contact("prh", "http://www.xxxxx.com", "1712405026@qq.com"))
    				// 描述
    				.description("欢迎访问xxxx接口文档，这里是描述信息")
    				// 定义版本号
    				.version("1.0").build();
    	}
    
    }

### 控制器中使用注解 ###

package com.sqtg.web;
    
    import io.swagger.annotations.ApiOperation;
    import io.swagger.annotations.ApiParam;
    import io.swagger.annotations.Api;
    
    @Api(tags = "AdController", description = "广告管理")
    @Controller
    @RequestMapping(value="ad")
    public class AdController { 
    
    	@Autowired
    	private IAdService adService;
    	
    	@Autowired
    	private ITradeService trade;
    	
    	@Autowired
    	private IScrollNotice notice;
    	
    	//json转换
    	final ObjectMapper objectMapper = new ObjectMapper();
    	
    	@Autowired
    	private RedisTemplate rt;
    	
    	/** * 轮播图列表 */
    	@ApiOperation(value = "轮播图列表", notes = "轮播图列表")
    	@RequestMapping(value = "/list", method = RequestMethod.GET)
    	@ResponseBody
    	public Result<Ad> getAdList(){ 
    		List<Ad> list = adService.getAdList();
    		System.out.println(list);
    		
    		return new Result<Ad>(ResultEnum.SUCCESS, list);
    	}
    }

以上就是Swagger-UI的基本配置了，访问localhost:8080/项目名称/swagger-ui.html就可以看到以下内容  
![f719a5837731b147a26b2b322cca63b1.png][]

[f719a5837731b147a26b2b322cca63b1.png]: /images/20221120/6e909b4dea0b4f2a9eb5c701a9829f47.png