第九节:SpringBoot在线文档Swagger2入门

Posted 入门小站

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了第九节:SpringBoot在线文档Swagger2入门相关的知识，希望对你有一定的参考价值。

SpringBoot集成Swagger2 3.0以下版本

pom.xml

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Swagger2Config配置文件

package com.rumenz.lession9.controller.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

/**
 * @className: Swagger2Config
 * @description: TODO 类描述
 * @author: 入门小站 rumenz.com
 * @date: 2021/11/10
 **/

@Configuration
@EnableSwagger2 //Swagger2 3.0以下版本需要开启的注解
public class Swagger2Config 

    @Bean
    public Docket docket()
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.rumenz.lession9.controller"))
                .paths(PathSelectors.any()).build();
    
    private ApiInfo apiInfo()
        Contact contact=new Contact("入门小站", "https://rumenz.com", "xenry@163.com");
        return new ApiInfoBuilder()
                .title("入门小站接口文档")
                .description("https://rumenz.com")
                .contact(contact).build();

SpringBoot集成Swagger2 3.0以版本

pom.xml

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

Swagger2Config配置问价相差不大。

package com.rumenz.lession9.controller.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

/**
 * @className: Swagger2Config
 * @description: TODO 类描述
 * @author: 入门小站 rumenz.com
 * @date: 2021/11/10
 **/

@Configuration
public class Swagger2Config 

    @Bean
    public Docket docket()
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.rumenz.lession9.controller"))
                .paths(PathSelectors.any()).build();
    
    private ApiInfo apiInfo()
        Contact contact=new Contact("入门小站", "https://rumenz.com", "xenry@163.com");
        return new ApiInfoBuilder()
                .title("入门小站接口文档")
                .description("https://rumenz.com")
                .contact(contact).build();

启动类添加注解

package com.rumenz;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;

@SpringBootApplication
@EnableOpenApi //Swagger2 3.0以上版本需要开启的注解
public class Lession9Application 

    public static void main(String[] args) 
        SpringApplication.run(Lession9Application.class, args);

Swagger2常用注解

@Api

@Api(tags = "入门小站Controller入口",value = "页面上看不见的内容")

@ApiOperation

@ApiOperation(value = "方法的作用说明",notes = "方法的备注说明")

@ApiImplicitParams,@ApiImplicitParam

@ApiImplicitParams(@ApiImplicitParam(name = "page",value = "当前页"),@ApiImplicitParam(name = "pageSize",value = "分页大小"))

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses

@ApiResponses(@ApiResponse(code = 200,message = "成功"),@ApiResponse(code=201,message = "参数错误"))

@ApiModel

@ApiModel("用戶信息")

@ApiModelProperty

@ApiModelProperty(value = "名字",name = "name",example = "入门小站")

演示案例

package com.rumenz.lession9.controller;

import io.swagger.annotations.*;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.web.bind.annotation.*;

/**
 * @className: RumenzController
 * @description: TODO 类描述
 * @author: 入门小站 rumenz.com
 * @date: 2021/11/10
 **/
@RestController
@RequestMapping("/rumenz")
//@Api用在类上,用于说明类功能的说明
@Api(tags = "入门小站Controller入口",value = "页面上看不见的内容")
public class RumenzController 

    @GetMapping("/index")
    public String index()
        return "入门小站";
    

    @GetMapping("/user")
    @ApiOperation(value = "方法的作用说明",notes = "方法的备注说明")
    //传入参数说明
    @ApiImplicitParams(@ApiImplicitParam(name = "page",value = "当前页"),@ApiImplicitParam(name = "pageSize",value = "分页大小"))
    //说明请求返回的状态码及描述
    @ApiResponses(@ApiResponse(code = 200,message = "成功"),@ApiResponse(code=201,message = "参数错误"))
    public String index1(@ApiParam("页数") @RequestParam("page") Integer page,@ApiParam("每页条数") Integer pageSize)
        return "入门小站";
    

    @PostMapping("/save")
    @ApiOperation("保存用户")
    public String save(@RequestBody User user)
        return "入门小站";
    


@Data
@NoArgsConstructor
@AllArgsConstructor
//描述实体类
@ApiModel("用戶信息")
class User 
    //描述实体类的属性
    @ApiModelProperty(value = "名字",name = "name",example = "入门小站")
    private String name;

    @ApiModelProperty(value = "年龄",name="age",example = "20")
    private Integer age;

    @ApiModelProperty(value = "地址",name="address",example = "rumenz.com")
    private String address;

    @ApiModelProperty(value = "邮箱",name="email",example = "372669319@qq.com")
    private String email;

  • 关注【入门小站】回复【1001】获取 linux常用命令速查手册
  • 关注【入门小站】回复【1003】获取 LeetCode题解【java语言实现】
  • 关注【入门小站】回复【1004】获取 Java基础核心总结
  • 关注【入门小站】回复【1009】获取 阿里巴巴Java开发手册

以上是关于第九节:SpringBoot在线文档Swagger2入门的主要内容，如果未能解决你的问题，请参考以下文章

SpringBoot集成Swagger2在线文档

SpringBoot整合Swagger2搭建API在线文档

SpringBoot整合Swagger-ui快速生成在线API文档

SpringBoot2.0系列教程Springboot框架添加Swagger2来在线自动生成接口的文档+测试功能

swagger在线文档和离线文档

SpringBoot整合Swagger2