Introduction to the

Meet Swagger:Swagger is a canonical and complete framework for generating, describing, invoking, and visualizing RESTful Web services. The overall goal is to have clients and file systems update at the same rate as servers. File methods, parameters, and models are tightly integrated into server-side code, allowing the API to always be in sync.

use

Import dependence

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

Configure the Config

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket(a){
    return newDocket(DocumentationType.SWAGGER_2); }}Copy the code

Docket

return new Docket(DocumentationType.SWAGGER_2).
                // Define some
                apiInfo(new ApiInfo(
                        "Api Document title"."Document Description"."Aip version"."TermOfService的URL".// Object, representing some information about the owner
                        new Contact(
                                "lin"."http://www.apache.org/licenses/LICENSE-2.0"."http://www.apache.org/licenses/LICENSE-2.0"),
                        "Apache 2.0"."http://www.apache.org/licenses/LICENSE-2.0".new ArrayList<>()))
                // Whether to enable Swagger, false to disable
                .enable(b)
                //select~build as a complete set
                .select()
                //apis define the classes to be included
                / / RequestHandlerSelectors configuration scan package way
                //any Scans all
                / / none do not scan
                //basePackage scans a packet
                //withClassAnnotation() scans the class under an annotation, such as withClassAnnotation(mapping.class), for all classes that have @mapping on their class
                //withMethodAnnotation() and withClassAnnotation() range changed from class to method
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.Controller"))
                // a method that allows you to define which controller to include based on the path map
                .paths(PathSelectors.ant("/demo/*"))
                .build();
Copy the code

Enable or disable Swagger based on multiple configurations

        // Set the Swagger environment to display
        Profiles of = Profiles.of("dev");
        // Determine if you are in the required environment
        boolean b = environment.acceptsProfiles(of);
Copy the code
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket(Environment environment){
        // Set the Swagger environment to display
        Profiles of = Profiles.of("dev");
        // Determine if you are in the required environment
        boolean b = environment.acceptsProfiles(of);
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(new ApiInfo(
                        "Api Document title"."Document Description"."Aip version"."TermOfService的URL".// Object, representing some information about the owner
                        new Contact(
                                "lin"."http://www.apache.org/licenses/LICENSE-2.0"."http://www.apache.org/licenses/LICENSE-2.0"),
                        "Apache 2.0"."http://www.apache.org/licenses/LICENSE-2.0".new ArrayList<>()))
                // Whether to enable Swagger, false to disable
                .enable(b)
                .select()
                //apis define the classes to be included
                / / RequestHandlerSelectors configuration scan package way
                //any Scans all
                / / none do not scan
                //basePackage scans a packet
                //withClassAnnotation() scans the class under an annotation, such as withClassAnnotation(mapping.class), for all classes that have @mapping on their class
                //withMethodAnnotation() and withClassAnnotation() range changed from class to method
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.Controller"))
                // a method that allows you to define which controller to include based on the path map
                .paths(PathSelectors.ant("/demo/*")) .build(); }}Copy the code

grouping

. GroupName (“A”) indicates A group

The following example is divided into three groups: A, B and INDEX

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket2(a){return new Docket(DocumentationType.SWAGGER_2).groupName("A"); }@Bean
    public Docket docket3(a){return new Docket(DocumentationType.SWAGGER_2).groupName("B"); }@Bean
    public Docket docket(Environment environment){return new Docket(DocumentationType.SWAGGER_2).groupName("index"); }Copy the code

test

  1. Define a User class
@AllArgsConstructor
@NoArgsConstructor
@Data
public class User {
    public String name;
    private String pwd;
}

Copy the code
  1. Let Swagger scan it
@Controller
public class HelloC {
    @ResponseBody
    @RequestMapping("/demo/hello")
    public String hello(a){
        return "hello";
    }
    // If there is an entity class in the interface, swagger will scan it
    @PostMapping("/demo/user")
    public User user(a){
        return newUser(); }}Copy the code
  1. Documentation comments

@APIModel and @APIModelProperty comment the document accordingly

@apiModel ("USer's documentation comments ")
public class User {
    @apiModelProperty (" username ")
    public String name;
    @ ApiModelProperty (" password ")
    private String pwd;

    public String getName(a) {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPwd(a) {
        return pwd;
    }

    public void setPwd(String pwd) {
        this.pwd = pwd; }}Copy the code

Note that you cannot comment a private property without adding a get method to it

@ ApiOperation () and @ ApiParam

@Controller
public class HelloC {
    // If there is an entity class in the interface, swagger will scan it
    @PostMapping("/demo/user")
    @apiOperation ("User's description ")
    public User user(@apiparam (" annotated n") String n){
        return newUser(); }}Copy the code

  1. test

We can test some objects with Swagger, but with Springboot note that the method that returns the object requires @responseBody