最新版swagger使用

1. maven导入swagger相关依赖

	<!-- Swagger API文档 开始 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-ui</artifactId>
            <version>3.0.3</version>
        </dependency>
     <!-- Swagger API文档 结束 -->

2. 配置Swagger配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;
import java.util.List;

/**
 * Swagger配置类
 */
@Configuration
@EnableOpenApi
public class SwaggerConfig {

    /**
     * 配置第一个swagger配置类，该类只扫描com.demo.swagger.test下的方法，并且分组为test
     * @return
     */

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo()).enable(true)
                // 允许忽略预定义的响应消息默认值
                .useDefaultResponseMessages(false)
                .select()
                /*
                 * 通过apis方法，basePackage可以根据包路径来生成特定类的API
                 * any方法是默认所有都有效，
                 * none方法都无效；
                 * withClassAnnotation根据类注解，withMethodAnnotation是根据方法注解；一般我们用的是 basePackage方法
                 */
                .apis(RequestHandlerSelectors.basePackage("com.demo.swagger.test"))
                /*
                 * 根据请求路径的paths方法
                 *  1.ant匹配路径
                 *  2.any是匹配任意路径
                 *  3.none是都不匹配
                 *  4.regex是正则匹配
                 */
                .paths(PathSelectors.any())
                .build().globalRequestParameters(parameter())
                .groupName("test");
    }


    /**
     * 配置第二个swagger配置类，该类只扫描com.demo.swagger.login下的方法，并且分组为登录服务
     * @return
     */
    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo()).enable(true)
                // 允许忽略预定义的响应消息默认值
                .useDefaultResponseMessages(false)
                .select()
                /*
                 * 通过apis方法，basePackage可以根据包路径来生成特定类的API
                 * any方法是默认所有都有效，
                 * none方法都无效；
                 * withClassAnnotation根据类注解，withMethodAnnotation是根据方法注解；一般我们用的是 basePackage方法
                 */
                .apis(RequestHandlerSelectors.basePackage("com.demo.swagger.login"))
                /*
                 * 根据请求路径的paths方法
                 *  1.ant匹配路径
                 *  2.any是匹配任意路径
                 *  3.none是都不匹配
                 *  4.regex是正则匹配
                 */
                .paths(PathSelectors.any())
                .build().globalRequestParameters(parameter())
                .groupName("登录服务");
    }

    /**
     * 文档描述信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger项目接口文档")
                .description("swagger项目描述")
                .contact(new Contact("jieya", "https://blog.csdn.net/u010913170/article/details/125081576", ""))
                .version("1.0")
                .build();
    }

    /**
     * 全局参数(如header中的token)
     *
     * @return List<Parameter>
     */
    private List<RequestParameter> parameter() {
        List<RequestParameter> globalRequestParameters = new ArrayList<>();
        RequestParameter authorization = new RequestParameterBuilder()
                //自定义字段
                .name("Authorization")
                // 描述
                .description("请求令牌(登录时不填写,其他接口请求需要此参数)")
                // 自定义字段的在哪里显示
                .in(ParameterType.HEADER)
                // 是否必填
                .required(false)
                .build();
        globalRequestParameters.add(authorization);
        return globalRequestParameters;
    }
}

3. 基本注解解析

• @Api : 用在类上，说明该类的主要作用。
• @ApiOperation：用在方法上，给API增加方法说明。
• @ApiImplicitParams : 用在方法上，包含一组参数说明。
• @ApiImplicitParam：用来注解来给方法入参增加说明。
• @ApiResponses：用于表示一组响应。
• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
• @ApiModel：用在返回对象类上，描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
• @ApiModelProperty：描述一个model的属性

4. 快速使用

	
import com.demo.model.dto.BasicModelDTO;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/login")
@Api(tags =  "登录服务")
public class LoginController {


    @GetMapping("/login")
    @ApiOperation(value = "登录")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query",name = "username", value = "用户名", required = true,dataType = "string"),
            @ApiImplicitParam(paramType = "query",name = "password", value = "密码", required = true,dataType = "string")
    })
    @ApiResponses({
            @ApiResponse(code = 2000, message = "登录成功"),
            @ApiResponse(code = 3000, message = "系统异常")
    })
    public BasicModelDTO login(String username, String password){
        return BasicModelDTO.builder().code(2000).message("登录成功").build();
    }
}

5. 测试

访问http://localhost:9090/doc.html