Introduction to the method of integrating SpringBoot with Swagger (with code)

This article brings you an introduction to the method of integrating Swagger with SpringBoot (with code). It has certain reference value. Friends in need can refer to it. I hope it will be helpful to you.

What is Swagger

1. Swagger can generate an interactive API console that developers can use to quickly learn and try APIs
2. Swagger can generate customers End SDK code is used for implementation on a variety of different platforms
3. Swagger files can be automatically generated from code comments on many different platforms
4. Swagger has a strong community

Dependency import

<!-- 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>

Add configuration

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: 1289747698@qq.com

Create 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();
    }
}

Through annotations Mark API

Swagger defaults to scanning all interfaces and generating corresponding API description and parameter information based on the configured package.

Commonly used annotations and corresponding attributes are as follows:

• @Api (Describes an API class, marked on the Controller)

  1. value: The path value of the url
  2. tags:If this value is set, the value of value will be overwritten
  3. description : Resource description of API
  4. basePath: The basic path does not need to be set
  5. produces: For example: application/json, application/xml Similar to RequestMapping corresponding attributes
  6. consumes: For example: application/json, application/xml
  7. authorizations: Configuration during advanced feature authentication
  8. hidden: Whether to hide in the document
     
     

• ##@ApiOperation (used on the Controller method , explain the function of the method)

  1. value:The path value of the url
  2. tags:If this value is set, the value of value will Overridden
  3. description:Description of API resources
  4. basePath:The base path may not be set
  5. position : If you configure multiple APIs and want to change the placement, you can set this property through
  6. response: Returned object
  7. responseContainer: These objects are valid List, Set, and Map, others are invalid
  8. httpMethod:Request method
  9. code:HTTP status code, default 200
  10. extensions：Extension attributes
      
      
• ##@ApiImplicitParams

  (used on Controller method , describing a set of request parameters)

  value:
  1. ApiImplicitParam array, see the next note
     
     
• @ApiImplicitParam

  (Describe a request parameter)

  name：
  1. Parameter name
  value：
  2. Parameter Value
  defaultValue:
  3. Parameter default value
  required:
  4. Whether it is required, default false
  access:
  5. Not too much description
  example：
  6. Example
     
     
##@ApiResponses
• (Description A set of responses)
  value:
  ApiResponse array, see next note
  1. 
     
     
@ApiResponse
• (Describe a response)
  code：
  HTTP status code
  1. message：
  Describe the message
  Finally, you can enter http://localhost:8080/swagger-ui.html in the browser to access!

The above is the detailed content of Introduction to the method of integrating SpringBoot with Swagger (with code). For more information, please follow other related articles on the PHP Chinese website!