0
0

Springboot集成Swagger3详细操作步骤

1、添加依赖

  1. <!-- 引入swagger3包 -->    
  2.  <dependency>
  3.     <groupId>io.springfox</groupId>
  4.     <artifactId>springfox-boot-starter</artifactId>
  5.     <version>3.0.0</version>
  6. </dependency>
  8. <!-- 引入swagger-bootstrap-ui包，优化UI页面，可不加 -->
  9. <dependency>
  10.     <groupId>com.github.xiaoymin</groupId>
  11.     <artifactId>swagger-bootstrap-ui</artifactId>
  12.     <version>1.8.5</version>
  13. </dependency>

2、添加配置文件resources\config\swagger.properties

  1. swagger.documentation-type=oas_30
  2. swagger.base-package=com.example.demo.db.controller
  3. swagger.api-info.title=demo_springboot
  4. swagger.api-info.description=xxx
  5. swagger.api-info.contact.name=JsonFling
  6. swagger.api-info.contact.email=jsonfling@xxxxxxxx.com
  7. swagger.api-info.contact.url=广东深圳

3、编写Swagger3Config配置类

  1. package com.example.demo.db.config;
  3. import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
  4. import org.springframework.boot.context.properties.ConfigurationProperties;
  5. import org.springframework.boot.context.properties.NestedConfigurationProperty;
  6. import org.springframework.context.annotation.*;
  7. import org.springframework.http.HttpMethod;
  8. import org.springframework.stereotype.Component;
  9. import springfox.documentation.builders.*;
  10. import springfox.documentation.oas.annotations.EnableOpenApi;
  11. import springfox.documentation.schema.ScalarType;
  12. import springfox.documentation.service.*;
  13. import springfox.documentation.spi.DocumentationType;
  14. import springfox.documentation.spring.web.plugins.Docket;
  16. import java.util.ArrayList;
  17. import java.util.List;
  18. import java.util.ResourceBundle;
  20. /**
  21.  * 描述： 单独定义 Swagger 配置类 profile 中包含 dev,sit,uat 任意一个时才会启动 Swagger （即生产环境不启动 Swagger） 环境变量
  22.  * SPRING_PROFILES_ACTIVE=dev/sit/uat 才启用该配置
  23.  */
  24. @Configuration
  25. //@Profile({"dev", "test", "uat"})
  26. @EnableOpenApi//会自动开启配置，启动类不需要加任何注解
  27. @EnableSwaggerBootstrapUI//访问美化，方便查看调试
  28. public class Swagger3Config {
  29.     /**
  30.      * @return Docket是swagger全局配置对象
  31.      */
  32.     @Bean
  33.     public Docket createApi(SwaggerProperties properties) {
  34.         return new Docket(properties.getDocumentationType().value)
  35.                 .apiInfo(createApiInfo(properties))
  36.                 .select()
  37.                 // 指定扫描的包，不指定会扫描出 spring 框架的接口，指定错误会导致接口扫描不出来
  38.                 .apis(RequestHandlerSelectors
  39.                         .basePackage(properties.getBasePackage()))
  40.                 .paths(PathSelectors.any())
  41.                 .build()
  42.                 .globalRequestParameters(getGlobalRequestParameters())//加入通用入参
  43.                 .globalResponses(HttpMethod.POST, getGlobalResonseMessage());//post方法加入通用响应头
  44.     }
  46.     /**
  47.      * API 文档基础信息，包括标题、联系人等
  48.      * @return ApiInfo
  49.      */
  50.     private ApiInfo createApiInfo(SwaggerProperties properties) {
  51.         SwaggerApiInfo apiInfoMeta = properties.getApiInfo();
  52.         SwaggerApiInfoContact contactMeta = apiInfoMeta.getContact();
  53.         Contact contact = new Contact(contactMeta.getName(), contactMeta.getUrl(), contactMeta.getEmail());
  54.         return new ApiInfoBuilder()
  55.                 .title(apiInfoMeta.getTitle())
  56.                 .description(apiInfoMeta.getDescription())
  57.                 .contact(contact)
  58.                 .build();
  59.     }
  61.     //定义文档类型，配置文件配置
  62.     public enum DocumentationTypeMode {
  63.         /**
  64.          * SWAGGER_12
  65.          */
  66.         SWAGGER_12(DocumentationType.SWAGGER_12),
  67.         /**
  68.          * SWAGGER_2
  69.          */
  70.         SWAGGER_2(DocumentationType.SWAGGER_2),
  71.         /**
  72.          * OAS_30
  73.          */
  74.         OAS_30(DocumentationType.OAS_30);
  76.         private final DocumentationType value;
  78.         DocumentationTypeMode(DocumentationType value) {
  79.             this.value = value;
  80.         }
  81.     }
  83.     @Component
  84.     @PropertySource(value = "classpath:/config/swagger.properties", ignoreResourceNotFound = true, encoding = "UTF-8")
  85.     @ConfigurationProperties(prefix = "swagger")
  86.     public static class SwaggerProperties {
  88.         private DocumentationTypeMode documentationType = DocumentationTypeMode.OAS_30;
  90.         private String basePackage = "com.example.demo.db.controller";
  92.         private SwaggerApiInfo apiInfo = new SwaggerApiInfo();
  94.         public DocumentationTypeMode getDocumentationType() {
  95.             return documentationType;
  96.         }
  98.         public void setDocumentationType(DocumentationTypeMode documentationType) {
  99.             this.documentationType = documentationType;
  100.         }
  102.         public String getBasePackage() {
  103.             return basePackage;
  104.         }
  106.         public void setBasePackage(String basePackage) {
  107.             this.basePackage = basePackage;
  108.         }
  110.         public SwaggerApiInfo getApiInfo() {
  111.             return apiInfo;
  112.         }
  114.         public void setApiInfo(SwaggerApiInfo apiInfo) {
  115.             this.apiInfo = apiInfo;
  116.         }
  117.     }
  118. //文档信息联系人实体类
  119.     public static class SwaggerApiInfoContact {
  120.         private String name;
  122.         private String url;
  124.         private String email;
  126.         public String getName() {
  127.             return name;
  128.         }
  130.         public void setName(String name) {
  131.             this.name = name;
  132.         }
  134.         public String getUrl() {
  135.             return url;
  136.         }
  138.         public void setUrl(String url) {
  139.             this.url = url;
  140.         }
  142.         public String getEmail() {
  143.             return email;
  144.         }
  146.         public void setEmail(String email) {
  147.             this.email = email;
  148.         }
  149.     }
  150.     //文档信息联系人实体类
  151.     public static class SwaggerApiInfo {
  153.         private String title;
  155.         private String description;
  157.         @NestedConfigurationProperty
  158.         private SwaggerApiInfoContact contact;
  160.         public String getTitle() {
  161.             return title;
  162.         }
  164.         public void setTitle(String title) {
  165.             this.title = title;
  166.         }
  168.         public String getDescription() {
  169.             return description;
  170.         }
  172.         public void setDescription(String description) {
  173.             this.description = description;
  174.         }
  176.         public SwaggerApiInfoContact getContact() {
  177.             return contact;
  178.         }
  180.         public void setContact(SwaggerApiInfoContact contact) {
  181.             this.contact = contact;
  182.         }
  183.     }
  185.     //生产通过接口入参
  186.     private List<RequestParameter> getGlobalRequestParameters() {
  187.         List<RequestParameter> parameters = new ArrayList<>();
  188.         parameters.add(new RequestParameterBuilder()
  189.                 .name("appid")
  190.                 .description("平台id")
  191.                 .required(true)
  192.                 .in(ParameterType.QUERY)
  193.                 .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
  194.                 .required(false)
  195.                 .build());
  196.         parameters.add(new RequestParameterBuilder()
  197.                 .name("udid")
  198.                 .description("设备的唯一id")
  199.                 .required(true)
  200.                 .in(ParameterType.QUERY)
  201.                 .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
  202.                 .required(false)
  203.                 .build());
  204.         parameters.add(new RequestParameterBuilder()
  205.                 .name("version")
  206.                 .description("客户端的版本号")
  207.                 .required(true)
  208.                 .in(ParameterType.QUERY)
  209.                 .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
  210.                 .required(false)
  211.                 .build());
  212.         return parameters;
  213.     }
  215.     //生成通用响应信息
  216.     private List<Response> getGlobalResonseMessage() {
  217.         List<Response> responseList = new ArrayList<>();
  218.         responseList.add(new ResponseBuilder()
  219.                 .code("404")
  220.                 .description("找不到资源")
  221.                 .build());
  222.         responseList.add(new ResponseBuilder()
  223.                 .code("0")
  224.                 .description("成功")
  225.                 .build());
  226.         responseList.add(new ResponseBuilder()
  227.                 .code("10")
  228.                 .description("系统异常")
  229.                 .build());
  230.         responseList.add(new ResponseBuilder()
  231.                 .code("20")
  232.                 .description("参数错误")
  233.                 .build());
  234.         responseList.add(new ResponseBuilder()
  235.                 .code("30")
  236.                 .description("系统异常")
  237.                 .build());
  238.         //或者通过枚举类添加
  239. //        for (ResponseStatusEnum value:ResponseStatusEnum.values()) {
  240. //            String code = String.valueOf(value.getCode());
  241. //            String message =value.getMessage();
  242. //                    responseList.add(new ResponseBuilder().code(code).description(message);
  243. //        }
  245.         return responseList;
  246.     }
  247. }

4、编写Ctronller类

  1. package com.example.demo.db.controller;
  3. import com.example.demo.db.domain.Student;
  4. import io.swagger.annotations.*;
  5. import org.springframework.web.bind.annotation.*;
  7. @Api(tags = "学生信息Controller")
  8. @RestController
  9. @RequestMapping(value = "/Student",method = RequestMethod.GET)
  10. public class StudentController{
  11.     @ApiOperation(value ="学生信息查询findAllStudent接口",notes = "注意点说明：接口通过id获取用户的详细信息，id必须传递")
  12.     @ApiImplicitParams({
  13.             @ApiImplicitParam(name = "sid", value = "用户id", required = true, dataType = "String", paramType = "query",defaultValue = "01"),
  14.             @ApiImplicitParam(name = "sname", value = "用户姓名", required = false, dataType = "String", paramType = "query",defaultValue = "赵雷"),
  15.     })
  16.     @RequestMapping(value = "/findAllStudent")
  17.     public Student  findAllStudent(String sid,String sname){
  18.         return null;
  19.     }
  21. }

5、启动访问地址：

http://localhost:8011/doc.html （加入UI优化依赖的访问路径）

http://localhost:8011/swagger-ui/index.html （原始路径）

6、Swagger3常用注解说明

@Api：用在请求的类上，说明该类的作用

参数：
tags：说明这个类的作用
value：这个参数没有什么意义，不需要配置

  1. @Api(tags = "学生信息Controller")

@ApiOperation：用在请求的方法上，说明方法的作用 

  1. 参数：
  2.  value：说明方法的作用
  3.   notes：方法的备注说明
  1.  @ApiOperation(value ="学生信息查询findAllStudent接口",notes = "注意点说明：接口通过id获取用户的详细信息，id必须传递")

@ApiImplicitParams和@ApiImplicitParam，和@ApiParam

（1） @ApiImplicitParams：用在请求的方法上，包含一组参数说明
（2）@ApiImplicitParams：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息
参数：
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
（3）@ApiParam：用在方法参数里，指定对应请求参数的配置信息

  1.  @ApiImplicitParams({
  2.             @ApiImplicitParam(name = "sid", value = "用户id", required = true, dataType = "String", paramType = "query",defaultValue = "01"),
  3.             @ApiImplicitParam(name = "sname", value = "用户姓名", required = false, dataType = "String", paramType = "query",defaultValue = "赵雷"),
  4.     })
  1. findAllStudent(@ApiParam(value = "id",name="id",required = true,defaultValue = "01") String id){

@ApiModel和@ApiModelProperty

（1）@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
（2）@ApiModelProperty：用在属性上，描述响应类的属性

  1. @ApiModel(value = "Student实体类",description = "学生实体对象")
  2. @Data
  3. public class Student implements Serializable {
  4.     @ApiModelProperty("学生id")
  5.     private String sid;
  6.     @ApiModelProperty("学生姓名")
  7.     private String sname;
  8.     @ApiModelProperty("学生年龄")
  9.     private Date sage;
  10.     @ApiModelProperty("学生性别")
  11.     private String ssex;
  13. }

@ApiResponses和@ApiResponse

（1）@ApiResponses：用于请求的方法上，表示一组响应
（2）@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

  1. @ApiResponses({
  2.     @ApiResponse(code=400,message="请求参数没填好"),
  3.     @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
  4. })
标签： spring boot java spring
本文转载自: https://blog.csdn.net/zhanhjxxx/article/details/122983553
版权归原作者 zhanhjxxx 所有， 如有侵权，请联系我们删除。
登录后发布评论

“Springboot集成Swagger3详细操作步骤”的评论:

还没有评论
关于作者
...
overfit同步小助手
文章同步
相关阅读

网络安全法-网络运行安全

使用selenium/drissionpage时如何阻止chrome自动跳转http到https

docker desktop 里部署的Open WebUI 管理员密码忘记了的处理方法

在ubuntu20.04中搭建onsite比赛运行环境

利用开源的低代码表单设计器FcDesigner高效管理和渲染复杂表单结构

Kafka学习笔记

【前端】浏览器输入url到页面呈现发生了什么？