美文网首页
springfox wagger2 自动生成接口文档[Sprin

springfox wagger2 自动生成接口文档[Sprin

作者: 温暖的纯真 | 来源:发表于2019-09-25 17:16 被阅读0次
    1. 添加依赖 pom.xml
            <!--JSON API文档的生成-->
            <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>
    
    1. 创建swagger配置文件SwaggerConfig.java
    @Configuration
    @EnableSwagger2
    @ConditionalOnExpression("${swagger.enable:true}")
    public class SwaggerConfig {
        @Bean
        public Docket swaggerSpringMvcPlugin(){
    
            ApiInfo apiInfo = new ApiInfoBuilder()
                    .title("** APIs")
                    .description("**的接口文档")
                    .version("1.0.0")
                    .termsOfServiceUrl(null)
                    .contact(new Contact("name", "url", "email"))
                    .license("作者:**")
                    .licenseUrl("http://")
                    .build();
    
            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    //.paths(regex("/api/*")) // 指定接口url 
                    .paths(PathSelectors.any())
                    .build()
                    .apiInfo(apiInfo)
                    .useDefaultResponseMessages(false);
    
            return docket;
        }
    }
    
    1. 配置具体的接口注释数据的简单示例,更多的注释可参看官网
      • @Api() 用于controller类
      • @ApiOperation()用于controller的方法
    ApiOperation(value = "/api/edit", notes = "", httpMethod = "POST", response = Response.class)
    
    • @ApiResponses用于controller的方法,响应的数据
    @ApiResponses({
            @ApiResponse(code = 100 , message = "请选择部门"),
            @ApiResponse(code = 101, message = "请选择日期")
    })
    
    • @ApiImplicitParams()用于controller的方法,参数注释
    @ApiImplicitParams({
            @ApiImplicitParam(name = "department", value = "部门", required = true, paramType = "form"),
            @ApiImplicitParam(name = "date", value = "日期", required = true, paramType = "form")
    })
    

    name 参数
    value 参数的描述
    required 是否必传
    paramType 参数存放位置:header、query、path(resuful接口)、body、form
    dataType 参数类型
    defaultValue 参数默认值

    • @ApiModel() 用于bean对象的类
    @ApiModel(value = "", description = "")
    
    • @ApiModelProperty()(用于bean对象的方法
    @ApiModelProperty(value = "", name="")
    

    value–字段说明
    name–重写属性名字
    dataType–重写属性类型
    required–是否必填
    example–举例说明
    hidden–隐藏

    • @ApiParam()具体请求参数
    @ApiParam(name = "", value = "", required = true)
    

    name 参数
    value 参数简单描述
    defaultValue 描述参数默认值
    allowableValues 可接收参数值限制
    required 是否为必传参数

    1. 与spring security配合
      使用了spring security时,需要登录访问,或者在security配置文件中添加对url的忽略。
    public class WebSecurityConfig extends WebSecurityConfigurerAdapter {
        @Override
        public void configure(WebSecurity web) throws Exception {
            web.ignoring().antMatchers(         
                    "/swagger-ui.html",
                     "/webjars/**",
                    "/v2/api-docs",
                    "/swagger-resources",
                    "/swagger-resources/configuration/ui",
                    "/swagger-resources/configuration/security"
                    );
        }
    }
    

    5.访问 ip:port/swagger-ui.html

    image.png
    1. 控制swagger关闭和启动
      SwaggerConfig.java中添加注释@ConditionalOnExpression("${swagger.enable:true}")
      application.properties更改:true启动,false关闭,线上系统需要关闭。

    相关文章

      网友评论

          本文标题:springfox wagger2 自动生成接口文档[Sprin

          本文链接:https://www.haomeiwen.com/subject/akfwuctx.html