SpringBoot 集成 Swagger

Posted 2021-02-14 dream-saddle

Swagger官网

什么是Swagger

1. Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API
2. Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现
3. Swagger 文件可以在许多不同的平台上从代码注释中自动生成
4. Swagger 有一个强大的社区

依赖导入

<!-- Swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

加入配置

swagger:
  title: 项目 API
  description: SpringBoot 集成 Swagger 项目 API
  version: 1.0
  terms-of-service-url: http://www.baidu.com/
  base-package: cn.anothertale.springbootshiro  # 这一项指定需要生成 API 的包，一般就是 Controller
  contact:
    name: taohan
    url: http://www.baidu.ccom/
    email: [email protected]

建立 Swagger Config

package cn.anothertale.springbootshiro.config.swagger;

import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.context.properties.ConfigurationProperties;
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;

/**
 * description: swagger 配置中心
 *
 * @author: taohan
 * @date: 2019年03月20日
 * @time: 16:52
 */
@Getter
@Setter
@Configuration
@EnableSwagger2
@ConditionalOnClass(EnableSwagger2.class)
@ConfigurationProperties(prefix = "swagger")
public class SwaggerConfig {

    /**
     * API 接口包路径
     */
    private String basePackage;

    /**
     * API 页面标题
     */
    private String title;

    /**
     * API 描述
     */
    private String description;

    /**
     * 服务条款地址
     */
    private String termsOfServiceUrl;

    /**
     * 版本号
     */
    private String version;

    /**
     * 联系人
     */
    private Contact contact;

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .version(version)
                .contact(contact)
                .build();
    }
}

通过注解标明 API

Swagger 默认根据配置的包，扫描所有接口并生成对应的 API 描述和参数信息。

常用注解及对应属性如下：

• @Api (描述一个 API 类，标注在 Controller 上)

  1. value：url 的路径值
  2. tags：如果设置该值，value 的值会被覆盖
  3. description：API 的资源描述
  4. basePath：基本路径可以不设置
  5. produces：比如：application/json, application/xml 类似 RequestMapping 对应属性
  6. consumes：比如：application/json, application/xml
  7. authorizations：高级特性认证时配置
  8. hidden：是否在文档中隐藏
     
     

• @ApiOperation (用在 Controller 方法上，说明方法的作用)

  1. value：url 的路径值
  2. tags：如果设置该值，value 的值会被覆盖
  3. description：对 API 资源的描述
  4. basePath：基本路径可以不设置
  5. position：如果配置多个 API 想改变展示位置，可通过该属性设置
  6. response：返回的对象
  7. responseContainer：这些对象是有效的 List、Set、Map，其他无效
  8. httpMethod：请求方式
  9. code：HTTP 状态码，默认200
  10. extensions：扩展属性
      
      

• @ApiImplicitParams (用在 Controller 方法上，描述一组请求参数)

  1. value：ApiImplicitParam 数组，见下一注解
     
     

• @ApiImplicitParam(描述一个请求参数)

  1. name：参数名称
  2. value：参数值
  3. defaultValue：参数默认值
  4. required：是否必须，默认 false
  5. access：不过多描述
  6. example：示例
     
     

• @ApiResponses (描述一组响应)

  1. value：ApiResponse数组，见下一注解
     
     

• @ApiResponse (描述一个响应)

  1. code：HTTP 的状态码
  2. message：描述消息

最后，可以在浏览器中输入 http://localhost:8080/swagger-ui.html 即可访问！