Swagger2配置使用

Swagger配置

pom文件引入：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

swaggerConfig文件

package com.minister.project.commen.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

/**
 * Swagger2 配置
 * <p>
 *     弃用，启用Knife4j
 * </p>
 *
 * @author Zj 2021/6/1 22:00
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    /**
     * 默认访问地址：
     *      http://localhost:8080/swagger-ui.html
     *
     *      swagger的bean实例 Docket
     */

    /**
     * 配置Swagger2的bean实例
     * enable(), 是否启用swagger,如果为false,则swagger不能再浏览器中访问
     */
    @Bean
    public Docket docketOfMinisterOL(Environment environment) {
        // 获取项目的环境：
        // 设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        // 通过environment.acceptsProfiles判断是否处在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfoOfMinisterOL())
                .groupName("1-MinisterOL")// swagger的分组列表排序默认是按照groupName来排序,Docket 排序方式(groupName): 1-10,a-z,A-Z
                .enable(flag)// enable(), 是否启用swagger,如果为false,则swagger不能再浏览器中访问
                .select()
                // RequestHandlerSelectors 配置需要扫描接口的方式
                //  basePackage(): 指定要扫描的包
                //  any(): 扫描全部
                //  none(): 不扫描
                //  withClassAnnotation(): 扫描类上的注解， 参数是一个注解的反射对象
                //  withMethodAnnotation(): 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.minister.project.controller"))
                // paths(): 指定路径
                //  PathSelectors.ant(): 只扫描该路径
                //  PathSelectors.any(): 全部扫描
                //  PathSelectors.none(): 不扫描
                //  PathSelectors.regex(): 通过正则表达式扫描
                //.paths(PathSelectors.ant("/minister/**"))
                .build();// select - build是一套，中间不能点其他的东西
    }

    @Bean
    public Docket docketOfSystem() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfoSystem())
                .groupName("2-System")
                .enable(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.minister.project.controller"))
                .build();// select - build是一套，中间不能点其他的东西
    }


    /**
     * 配置Swagger信息 apiInfo
     *
     * @return
     */
    private ApiInfo apiInfoOfMinisterOL() {
        // 作者信息
        Contact contactInfo = new Contact("Zj", "https://blog.csdn.net/MinisterOL", "zhengjun0525@163.com");

        return new ApiInfo(
                "MinisterOL Api Documentation",
                "Api Documentation By Zj",
                "V 0.1",
                "https://blog.csdn.net/MinisterOL",
                contactInfo,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

    private ApiInfo apiInfoSystem() {
        // 作者信息
        Contact contactInfo = new Contact("Zj", "https://blog.csdn.net/MinisterOL", "zhengjun0525@163.com");

        return new ApiInfo(
                "System Api Documentation",
                "Api Documentation By Zj",
                "V 0.1",
                "https://blog.csdn.net/MinisterOL",
                contactInfo,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

    /**
     * @Api：用在请求的类上，表示对类的说明
     *     tags="说明该类的作用，可以在UI界面上看到的注解"
     *     value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
     *
     * @ApiOperation：用在请求的方法上，说明方法的用途、作用
     *     value="说明方法的用途、作用"
     *     notes="方法的备注说明"
     *
     * @ApiImplicitParams：用在请求的方法上，表示一组参数说明
     *     @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
     *         name：参数名
     *         value：参数的汉字说明、解释
     *         required：参数是否必须传
     *         paramType：参数放在哪个地方
     *             · header --> 请求参数的获取：@RequestHeader
     *             · query --> 请求参数的获取：@RequestParam
     *             · path（用于restful接口）--> 请求参数的获取：@PathVariable
     *             · body（不常用）
     *             · form（不常用）
     *         dataType：参数类型，默认String，其它值dataType="Integer"
     *         defaultValue：参数的默认值
     *
     * @ApiResponses：用在请求的方法上，表示一组响应
     *     @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
     *         code：数字，例如400
     *         message：信息，例如"请求参数没填好"
     *         response：抛出异常的类
     *
     * @ApiModel：用于响应类上，表示一个返回响应数据的信息
     *             （这种一般用在post创建的时候，使用@RequestBody这样的场景，
     *             请求参数无法使用@ApiImplicitParam注解进行描述的时候）
     *     @ApiModelProperty：用在属性上，描述响应类的属性
     */
}

controlller层

package com.minister.project.controller;

import com.minister.project.entity.dto.system.LoginDto;
import com.minister.project.entity.vo.system.LoginVo;
import com.minister.project.commen.utils.result.Result;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import javax.validation.Valid;

/**
 * 系统基础接口
 *
 * @author Zj 2021/6/6 12:32
 */
@Api(tags = "系统基本接口")
@RestController
public class SystemController {

    /**
     * 登录接口
     */
    @ApiOperation(value = "1-登录接口", notes = "系统登录接口，是系统的一个入口")
    @PostMapping("/login")
    public Result<LoginVo> login(@Valid @RequestBody LoginDto dto) {
        LoginVo loginVo = new LoginVo();
        loginVo.setUserName("用户名").setToken("token");
        return Result.success(loginVo);
    }

}

请求参数

package com.minister.project.entity.dto.system;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import javax.validation.constraints.NotBlank;

/**
 * 登陆接口请求参数
 *
 * @author Zj 2021/6/6 16:24
 */
@Data
@ApiModel
public class LoginDto {

    @ApiModelProperty(value = "账号", position = 1)
    @NotBlank(message = "请输入账号")
    private String account;

    @ApiModelProperty(value = "密码", position = 2)
    @NotBlank(message = "密码不能为空")
    private String password;

}

返回参数配置

package com.minister.project.entity.vo.system;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;

/**
 * 登录接口返回参数
 *
 * @author Zj 2021/6/6 15:46
 */
@Data
@ApiModel
@AllArgsConstructor
@NoArgsConstructor
@Accessors(chain = true)
public class LoginVo {

    @ApiModelProperty(value = "用户名", position = 1)
    private String userName;

    @ApiModelProperty(value = "token标识", position = 2)
    private String token;

}