Swagger第一话 -- Springboot集成Swagger及使用

需求变化快，api文档写到吐？字段漏掉或者更新不及时？
集成这东西后，那就都不是问题，这就是Swagger

1.环境依赖

基于spring-boot-starter-parent 2.6.8，引入依赖

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

2.代码初始化

import io.swagger.models.auth.In;
import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

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

/**
 * api页面 http://127.0.0.1:8080/swagger-ui/index.html
 * 老版本是http://127.0.0.1:8080/swagger-ui.html
 */
@Profile({"dev", "test"})
@Configuration
@EnableSwagger2
public abstract class SwaggerConf {

    @Bean
    @SuppressWarnings("all")
    public Docket createRestApi() {
        ParameterBuilder ticketPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        //自定义参数和默认值
//        ticketPar.name(SecurityConstant.HEADER_STRING).description("token")
//                .modelRef(new ModelRef("string"))
//                .parameterType("header")
//                .defaultValue(SecurityConstant.TOKEN_PREFIX + " ")
//                .required(true)
//                .build();
//        pars.add(ticketPar.build());
        return new Docket(DocumentationType.OAS_30)
                .enable(true)
                .apiInfo(apiInfo())
                .securitySchemes(this.securitySchemes())
                .securityContexts(this.securityContexts())
                .select()
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .description("cms 业务处理")
                .title("cms 业务接口文档")
                .version("1.0")
                .build();
    }


    /**
     * 设置授权信息
     */
    private List<SecurityScheme> securitySchemes() {
        ApiKey apiKey = new ApiKey("Authorization", "JWT", In.HEADER.toValue());
        return Collections.singletonList(apiKey);
    }

    /**
     * 授权信息全局应用
     */
    private List<SecurityContext> securityContexts() {
        return Collections.singletonList(
                SecurityContext.builder()
                        .securityReferences(Collections.singletonList(
                                new SecurityReference("Authorization",
                                        new AuthorizationScope[]{new AuthorizationScope("global", "")})))
                        .build()
        );
    }
}

3.代码中使用

两个接口，一个实体类

@Api(tags = "app:代理业务")
@RestController
@RequestMapping("/api")
public class ChannelController {

	@ApiOperation(value = "get接口传参",notes = "name必传")
	@GetMapping("/test")
    public String test(@ApiParam(required = true,name = "名称") @RequestParam String name) {
        return "hello";
    }

	@ApiOperation(value = "post接口传参",notes = "接收agent实体类")
    @PostMapping("/hello")
    public String hello(@RequestBody AgentVO agentVO) {
        return "";
    }
}

//AgentVO实体类
@ApiModel("渠道商信息bean")
@Slf4j
@Data
public class AgentVO extends Agent {

    @ApiModelProperty("渠道码")
    String agentCode;

    @ApiModelProperty("渠道名")
    String agentName;
	@ApiModelProperty("推广app ids")
    String appIds;
 }

4.对应的截图

• 首页截图
  

• get接口详细截图
  

• post接口详细截图
  
  返回值如果为实体类，也可以在swagger上体现。既能显示还能调用接口，巴适。
  注意：上传文件且带参时，不支持在这里调用

以上就是本章的全部内容了。

上一篇：Jpa第一话 – Springboot集成Jpa以及Jpa的最全使用
下一篇：SpringSecurity第一话 – 一文来吃透SpringSecurity+Jwt权限控制

莫倚儿童轻岁月，丈人曾共尔同年