swagger2 使用说明_apimodelproperty extensions

作者：花生_TL007 | 2024-04-06 16:28:49

踩

apimodelproperty extensions

swagger2 使用说明

作用：生成在线文档，并支持在线测试

*************************

导入 jar 包


        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

*************************

自动配置类

OpenApiAutoConfiguration


@Configuration
@EnableConfigurationProperties({SpringfoxConfigurationProperties.class})
@ConditionalOnProperty(
    value = {"springfox.documentation.enabled"},
    havingValue = "true",
    matchIfMissing = true
)
@Import({OpenApiDocumentationConfiguration.class, SpringDataRestConfiguration.class, BeanValidatorPluginsConfiguration.class, Swagger2DocumentationConfiguration.class, SwaggerUiWebFluxConfiguration.class, SwaggerUiWebMvcConfiguration.class})
@AutoConfigureAfter({WebMvcAutoConfiguration.class, JacksonAutoConfiguration.class, HttpMessageConvertersAutoConfiguration.class, RepositoryRestMvcAutoConfiguration.class})
public class OpenApiAutoConfiguration {
    public OpenApiAutoConfiguration() {
    }
}

自动配置类导入：OpenApiDocumentationConfiguration、SpringDataRestConfiguration、

BeanValidatorPluginsConfiguration、Swagger2DocumentationConfiguration、

SwaggerUiWebFluxConfiguration、SwaggerUiWebMvcConfiguration

SpringfoxConfigurationProperties


@ConfigurationProperties("springfox.documentation")
public class SpringfoxConfigurationProperties {
 
    private boolean autoStartup = true;
    private boolean enabled = true;
 
    @NestedConfigurationProperty
    private SpringfoxConfigurationProperties.SwaggerConfigurationProperties swagger;
 
    @NestedConfigurationProperty
    private SpringfoxConfigurationProperties.OpenApiConfigurationProperties openApi;
 
    @NestedConfigurationProperty
    private SpringfoxConfigurationProperties.SwaggerUiConfigurationProperties swaggerUi;
 
    public SpringfoxConfigurationProperties() {
    }
 
 
**************
内部类：SwaggerUiConfigurationProperties
 
    public static class SwaggerUiConfigurationProperties {
        private boolean enabled = true;
        private String baseUrl = "";       //swagger-ui访问根路径
 
        public SwaggerUiConfigurationProperties() {
        }
 
 
 
**************
内部类：OpenApiConfigurationProperties
 
    public static class OpenApiConfigurationProperties {
        private boolean enabled = true;
 
        public OpenApiConfigurationProperties() {
        }
 
 
**************
内部类：Swagger2Configuration
 
    public static class Swagger2Configuration {
        private boolean enabled = false;
        private boolean useModelV3 = true;     //默认使用modelV3格式
        private String host;
 
 
**************
内部类：SwaggerConfigurationProperties
 
    public static class SwaggerConfigurationProperties {
        @NestedConfigurationProperty
        private SpringfoxConfigurationProperties.Swagger2Configuration v2;
 
        public SwaggerConfigurationProperties() {
        }

SwaggerUiWebMvcConfiguration：swagger-ui 访问配置


@Configuration
@ConditionalOnWebApplication(
    type = Type.SERVLET
)
@ConditionalOnProperty(
    value = {"springfox.documentation.swagger-ui.enabled"},
    havingValue = "true",
    matchIfMissing = true
)
public class SwaggerUiWebMvcConfiguration {
    @Value("${springfox.documentation.swagger-ui.base-url:}")
    private String swaggerBaseUrl;       //swagger-ui 访问根路径
 
    public SwaggerUiWebMvcConfiguration() {
    }
 
    @Bean
    public SwaggerUiWebMvcConfigurer swaggerUiConfigurer() {
        return new SwaggerUiWebMvcConfigurer(this.fixup(this.swaggerBaseUrl));
    }  //创建 SwaggerUiWebMvcConigurer 实例
 
    private String fixup(String swaggerBaseUrl) {
        return StringUtils.trimTrailingCharacter(BuilderDefaults.nullToEmpty(swaggerBaseUrl), '/');
    }
}

SwaggerUiWebMvcConfigurer


public class SwaggerUiWebMvcConfigurer implements WebMvcConfigurer {
    private final String baseUrl;
 
    public SwaggerUiWebMvcConfigurer(String baseUrl) {
        this.baseUrl = baseUrl;
    }
 
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        String baseUrl = StringUtils.trimTrailingCharacter(this.baseUrl, '/');
        registry.addResourceHandler(new String[]{baseUrl + "/swagger-ui/**"}).addResourceLocations(new String[]{"classpath:/META-INF/resources/webjars/springfox-swagger-ui/"}).resourceChain(false);
    }
 
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController(this.baseUrl + "/swagger-ui/").setViewName("forward:" + this.baseUrl + "/swagger-ui/index.html");
    }  //this.baseUrl + "/swagger-ui/ ==> this.baseUrl + "/swagger-ui/index.html"
}

说明：使用 localhost:8080/swagger-ui/、localhost:8080/swagger-ui/index.html 可访问swagger-ui 界面

*************************

相关注解

*******************

pojo 注解

@ApiModel：对实体类进行说明


@Target({ElementType.TYPE})             //标注在类上
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface ApiModel {
 
    String value() default "";         //对类的作用进行说明
    String description() default "";   //描述信息
 
    Class<?> parent() default Void.class;
    String discriminator() default "";
    Class<?>[] subTypes() default {};
    String reference() default "";
}

@ApiModelProperty：对实体类的属性说明


@Target({ElementType.METHOD, ElementType.FIELD})  //标注在方法、字段上
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiModelProperty {
 
    String name() default "";          //字段名称
    String value() default "";         //字段说明
 
    String dataType() default "";      //字段类型，如：String、Integer
    boolean required() default false;  //是否必须
 
    String allowableValues() default "";
    String access() default "";
    String notes() default "";
    String example() default "";
    String reference() default "";
 
    int position() default 0;
 
    boolean hidden() default false;
    boolean allowEmptyValue() default false;
 
    ApiModelProperty.AccessMode accessMode() default ApiModelProperty.AccessMode.AUTO;
 
 
    Extension[] extensions() default {@Extension(
    properties = {@ExtensionProperty(
    name = "",
    value = ""
)}
)};
 
    public static enum AccessMode {
        AUTO,
        READ_ONLY,
        READ_WRITE;
 
        private AccessMode() {
        }
    }
}

*******************

controller 相关注解

@Api：对控制器进行说明


@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface Api {
 
    String value() default "";           //类作用说明
    String[] tags() default {""};        //类说明，可有多个，如：tags={"des","des2"}
 
    String produces() default "";
    String consumes() default "";
    String protocols() default "";
 
    boolean hidden() default false;
    Authorization[] authorizations() default {@Authorization("")};
 
}

@ApiOperation：对控制器的方法进行说明


@Target({ElementType.METHOD, ElementType.TYPE})      //注解在类、方法上
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiOperation {
 
    String value();                  //方法说明
    String notes() default "";       //方法详细说明
    String[] tags() default {""};    //方法说明，可有多个
 
    Class<?> response() default Void.class;
 
    String responseContainer() default "";
    String responseReference() default "";
    String httpMethod() default "";
 
    String nickname() default "";
    String produces() default "";
    String consumes() default "";
    String protocols() default "";
 
    Authorization[] authorizations() default {@Authorization("")};
 
    boolean hidden() default false;
 
    ResponseHeader[] responseHeaders() default {@ResponseHeader(
    name = "",
    response = Void.class
)};
 
    int code() default 200;
 
    Extension[] extensions() default {@Extension(
    properties = {@ExtensionProperty(
    name = "",
    value = ""
)}
)};
 
    boolean ignoreJsonView() default false;
}

@ApiParam：对控制器方法参数进行说明


@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})   //注解在参数、方法、字段上
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiParam {
 
    String name() default "";             //参数名称
    String value() default "";            //参数说明
 
    String defaultValue() default "";     //参数默认值
    boolean required() default false;     //参数是否必须
 
    String access() default "";
    String allowableValues() default "";
 
    boolean allowMultiple() default false;
    boolean hidden() default false;
 
    String example() default "";
 
    Example examples() default @Example({@ExampleProperty(
    mediaType = "",
    value = ""
)});
 
    String type() default "";
    String format() default "";
 
    boolean allowEmptyValue() default false;
    boolean readOnly() default false;
 
    String collectionFormat() default "";
}

@ApiImplicitParam：对控制器方法的参数进行说明


@Target({ElementType.METHOD})             //标注在方法上
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiImplicitParam {
 
    String name() default "";        //参数名称（方法体中参数名）
    String value() default "";       //参数说明（对参数进行描述）
 
    boolean required() default false;     //参数是否必须
    String defaultValue() default "";     //参数的默认值
 
    String paramType() default "";       //参数请求类型，如：query（自定义，为查询参数）
    String dataType() default "";        //参数类型，如：string、Integer
 
    String access() default "";
    String allowableValues() default "";
    boolean allowMultiple() default false;
 
    Class<?> dataTypeClass() default Void.class;
 
    String example() default "";
 
    Example examples() default @Example({@ExampleProperty(
    mediaType = "",
    value = ""
)});
 
    boolean allowEmptyValue() default false;
    boolean readOnly() default false;
 
    String type() default "";
    String format() default "";
    String collectionFormat() default "";
}

@ApiImplicitParams：对控制器方法参数进行说明


@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiImplicitParams {
    ApiImplicitParam[] value();    //ApiImplicitParam数组，通常标注在控制器方法上对参数进行说明
}

@ApiResponse：对控制器方法返回数据进行说明


@Target({ElementType.METHOD})       //标注在方法上
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiResponse {
 
    int code();                      //响应码，如：403
    String message();                //响应码对应的说明信息
 
    Class<?> response() default Void.class;
    String reference() default "";
 
    ResponseHeader[] responseHeaders() default {@ResponseHeader(
    name = "",
    response = Void.class
)};
 
    String responseContainer() default "";
 
    Example examples() default @Example({@ExampleProperty(
    value = "",
    mediaType = ""
)});
}

@ApiResponses：对控制器方法返回数据进行说明


@Target({ElementType.METHOD, ElementType.TYPE})      //标注在方法、类上
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiResponses {
    ApiResponse[] value();         //使用apiResponse数组对控制器参数返回数据进行说明
}

声明：本文内容由网友自发贡献，不代表【wpsshop博客】立场，版权归原作者所有，本站不承担相应法律责任。如您发现有侵权的内容，请联系我们。转载请注明出处：https://www.wpsshop.cn/w/花生_TL007/article/detail/373053