How to use Swagger2 and annotation explanation in SpringBoot project

1. Import Swagger coordinate dependencies

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

The most commonly used version is 2.9.2

2. Add annotations to the spring startup class@ EnableSwagger2

The @EnableSwagger2 annotation provided by springfox can enable swagger2 related technologies. The program will traverse all types in the package and its sub-packages of the current class to find annotations related to Swagger and customize the Swagger document

3. Start the project and view the swaggerui.html interface

Click try it out to enter the corresponding parameters to view the returned results

Fourth, write the SwaggerConfig configuration file

@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Autowired
    private ApplicationContext applicationContext;

    private Contact contact = new Contact("NIUA","localhost:8080/swagger-ui.html", "1053288979@qq.com");

    @Bean
    public Docket createRestApi() {
        ServletContext servletContext = applicationContext.getBean(ServletContext.class);
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(regex("/error.*")))
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("平台接口 v1.0")
                .description("平台接口")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

@Bean
    public Docket createRestApi() {
        ServletContext servletContext = applicationContext.getBean(ServletContext.class);
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(regex("/error.*")))
                .build()
                .apiInfo(apiInfo());
    }

Create a Docker type object and use spring container management. Docker is the global configuration object in Swagger

Use DocumentationType.SWAGGER_2 to specify the class object of Docket to determine which version is used

apiInfo(): Description information of the API document, the parameter is one ApiInfo class object, use the bulid() builder to create

private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("平台接口 v1.0")
               .description("平台接口")
               .contact(contact)
               .version("1.0")
               .build();
   }

contact(): Configure the main content of the swagger document, which is also a class object. The class object can have up to three parameters, Publisher name, document publisher's website URL address (corporate website), document publisher's email address

private Contact contact = new Contact("NIUA","localhost:8080/swagger-ui.html", "1053288979@qq.com");

title(): Title description(): Description information.version(): Version information

corresponds to the following content

The method that returns ApiSelectorBuilder is select(), which is used to obtain the selector in Docker. Build selectors. For example, what packages should be scanned for annotations

apis(): followed by the (Predicate) rules under the RequestHandlerSelectors class, which stipulates the annotations of those packages to be scanned. The default is the annotations under the startup class and its sub-packages

There are several static methods under the RequestHandlerSelectors class (three examples)

basePackage(): Fill in the specific address of the package name later, and the annotations of the modified package and its sub-packages will be scanned

docker.apis(RequestHandlerSelectors.basePackage("com.xxx"))

any(): Generate API documentation for any interface

none(): Do not generate interface documentation for any interface

path(): Use regular expressions, constraint generation The path address of the Api document, followed by the filtered (passed) path

//过滤掉admin路径下的所有页面
.paths(Predicates.not(PathSelectors.regex("/admin/.*")))
//过滤掉所有error或error.*页面
.paths(Predicates.not(PathSelectors.regex("/error.*")))

//所有error或error.*页面或者admin路径下的所有页面都支持（or任意满足起一就通过）
.paths(Predicates.or(PathSelectors.regex("/error.*"),PathSelectors.regex("/admin/.*")))

5: Swagger supports custom annotations

is not mentioned here, you can search it yourself if you are interested (leave a Location, will be used later)

Six: Swagger2 common annotations

@Api (commonly used)

Function : @Api is a class Note on. Control the content of the interface information generated by the entire class

Attributes:

tags: The name of the class. If there are multiple values, which means there are multiple copies (aliases) available, the SwaggerUI view will show which controllers have access to the menu through which

description: description, obsolete

@ApiOperation

Function: @ApiOperation is an annotation on the method, describing the relevant information of the method

Attributes：

value：Method description function

notes：Method notes (expand description)

@ApiParm

Function: @ApiParm is a method parameter annotation. Describe the parameter

Attribute:

name:Parameter name

value:Describe the function of the parameter

required:The value is of boolean type , indicating whether the parameter is a necessary parameter, the default is false

@ApiIgnore

作用：@ApiParm是方法或者参数的注解。忽略注解的方法或者参数，不生成帮助文档

@ApiImplicitParam(常用)

作用：@ApiParm是作用于类上方法，用来描述方法参数的注解。

属性：

name：参数名称，和方法的参数一致

value：参数具体描述

required：值为boolean类型，表示该参数是否为必要参数，默认为false

paramType：参数类型

paramType="字符串"
paramType = "header"

dataType：数据类型

dataType = "string"  //字符串数据
dataType = "键值对"

@ApiImplicitParams

后面跟@ApiImplicitParam的集合，一般用于多个参数的描述

@ApiImplicitParams({@ApiImplicitParam(name = "Authorization", value = "Authorization token", required = true, dataType = "string", paramType = "header")})

@ApiModel(常用)

作用：@ApiModel是作用于实体类上，描述一个实体类型，整个实体类型如果成为任何一个生成api帮助文档的返回对象的时候，该注解被解析

属性：

value：实体类名称

description：实体类描述

@ApiModelProperty(常用)

作用：@ApiModel是作用于实体类的属性上，描述实体类属性

属性：

value：实体属性描述

name：实体类属性名字，与属性名一致

The above is the detailed content of How to use Swagger2 and annotation explanation in SpringBoot project. For more information, please follow other related articles on the PHP Chinese website!