何白白

我的java开发记录


Project maintained by hjx601496320 Hosted on GitHub Pages — Theme by mattgraham

swagger-ui简要使用说明

配置说明

添加依赖

与springboot 进行集成的时候版本尽可能的新。不然在页面上会有错误产生。

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

添加项目配置

在和springboot 进行集成的时候,因为springboot默认不会添加jar中的资源文件,导致api页面不能显示,所以需要手动的设置资源文件


import io.swagger.annotations.Api;
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.WebMvcConfigurer;
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;


/**
 * SwaggerConfig
 */
@EnableSwagger2
@Configuration
public class SwaggerConfig implements WebMvcConfigurer {

    /**
     * 添加资源文件映射
     *
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("标题")
                .description("描述")
                .contact("创建人")
                .version("1.0").build();
    }

}

API详细说明

作用范围 API 使用位置
对象属性 @ApiModelProperty 用在出入参数对象的字段上
协议集描述 @Api 用于controller类上
协议描述 @ApiOperation 用在controller的方法上
Response集 @ApiResponses 用在controller的方法上
Response @ApiResponse 用在 @ApiResponses里边
非对象参数集 @ApiImplicitParams 用在controller的方法上
非对象参数描述 @ApiImplicitParam 用在@ApiImplicitParams的方法里边
描述返回对象的意义 @ApiModel 用在返回对象类上

注解

@ApiImplicitParam

属性 取值 作用
paramType   查询参数类型
  path 以地址的形式提交数据
  query 直接跟参数完成自动映射赋值
  body 以流的形式提交 仅支持POST
  header 参数在request headers 里边提交
  form 以form表单的形式提交 仅支持POST
dataType   参数的数据类型 只作为标志说明,并没有实际验证
  Long long
  String String
  其他的
name   接收参数名
value   接收参数的意义描述
required   参数是否必填
  true  
  false  
defaultValue   默认值

使用

在配置完成之后,访问:http://你的项目地址/swagger-ui.html,就可以看到api文档。