搭建单体SpringBoot项目 集成Swagger接口文档

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>
<!-- 官方UI包 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

import io.swagger.annotations.ApiOperation;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration    //表明当前类是配置类
@EnableOpenApi    //表示开启生成接口文档功能（只有开启了OpenApi,才可以实现生成接口文档的功能）
@EnableSwagger2
public class SwaggerConfig {
    @Bean("swagger-1")
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("swagger-1")
                .apiInfo(apiInfo())
                .select()
                .apis( RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean("swagger-2")
    public Docket createRest2Api() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("swagger-2")
                .apiInfo(apiInfo())
                .select()
                .apis( RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("熊猫code管理项目接口文档" + System.currentTimeMillis())//标题
                .description("熊猫code知识库平台 https://pandacode.cn")//描述
                // 附加信息
                .version("1.0")//版本
                .build();
    }
}

@RestController
@Api("测试controller")
public class TestController {
    @ApiOperation("测试接口")
    @GetMapping("/panda/swagger/test/")
    public void test(@ApiParam("阿拉啦啦") String param1) {
    }
}

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

@Path("/pet")
@Api(value = "pet", authorizations = {
      @Authorization(value="sampleoauth", scopes = {})
    })
@Produces({"application/json", "application/xml"})
public class PetResource {
 ...
}

@Api(tags = {"external_info","user_info"})

@GET
@Path("/findByStatus")
@ApiOperation(value = "Finds Pets by status",
   notes = "Multiple status values can be provided with comma seperated strings",
   response = Pet.class,
   responseContainer = "List")
public Response findPetsByStatus(...) { ... }

  "/pet/findByStatus": {
"get": {
  "tags": [
    "pet"
  ],
  "summary": "Finds Pets by status",
  "description": "Multiple status values can be provided with comma seperated strings",
  "responses": {
    "200": {
      "description": "successful operation",
      "schema": {
        "type": "array",
        "items": {
          "$ref": "#/definitions/Pet"
        }
      }
    },
    .
    .
    .

@ApiResponses(value = { 
    @ApiResponse(code = 400, message = "Invalid ID supplied", 
                 responseHeaders = @ResponseHeader(name = "X-Rack-Cache", description = "Explains whether or not a cache was used", response = Boolean.class)),
    @ApiResponse(code = 404, message = "Pet not found") })
public Response getPetById(...) {...}

@ApiOperation(value = "Add a new pet to the store", 
  authorizations = {
    @Authorization(
        value="petoauth", 
        scopes = { @AuthorizationScope(scope = "add:pet") }
        )
  }
)
public Response addPet(...) {...}

"security": [
  {
    "petoauth": [
      "add:pet"
    ]
  }
]

 @Path("/{username}")
 @ApiOperation(value = "Updated user",
    notes = "This can only be done by the logged in user.")
public Response updateUser(
      @ApiParam(value = "name that need to be updated", required = true) @PathParam("username") String username,
      @ApiParam(value = "Updated user object", required = true) User user) {...}

 "parameters": [
  {
    "name": "username",
    "in": "path",
    "description": "name that need to be deleted",
    "required": true,
    "type": "string"
  },
  {
    "in": "body",
    "name": "body",
    "description": "Updated user object",
    "required": true,
    "schema": {
      "$ref": "#/definitions/User"
    }
  }
]

@ApiImplicitParams({
   @ApiImplicitParam(name = "name", value = "User's name", required = true, dataType = "string", paramType = "query"),
   @ApiImplicitParam(name = "email", value = "User's email", required = false, dataType = "string", paramType = "query"),
   @ApiImplicitParam(name = "id", value = "User ID", required = true, dataType = "long", paramType = "query")
 })
public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {...}

 "parameters": [
  {
    "name": "name",
    "description": "User's name",
    "required": true,
    "type": "string",
    "in": "query"
  },
  {
    "name": "email",
    "description": "User's email",
    "required": false,
    "type": "string",
    "in": "query"
  },
  {
    "name": "id",
    "description": "User ID",
    "required": true,
    "type": "integer",
    "format": "int64",
    "in": "query"
  }
]

@ApiResponses(value = { 
    @ApiResponse(code = 400, message = "Invalid ID supplied", 
                 responseHeaders = @ResponseHeader(name = "X-Rack-Cache", description = "Explains whether or not a cache was used", response = Boolean.class)),
    @ApiResponse(code = 404, message = "Pet not found") })
public Response getPetById(...) {...}

@ApiModel(value="DifferentModel", description="Sample model for the documentation")
class OriginalModel {...}

"DifferentModel": {
     "description": "Sample model for the documentation",
     .
     .
 }

@ApiModel(value = "Pet", subTypes = {Cat.class})
public class Pet {

}

@ApiModelProperty(value = "pet status in the store", allowableValues = "available,pending,sold")
public String getStatus() {
  return status;
}

"properties": {
      ...,
      "status": {
        "type": "string",
        "description": "pet status in the store",
        "enum": [
          "available",
          "pending",
          "sold"
        ]
      }
    }

@SwaggerDefinition(
        info = @Info(
                description = "Gets the weather",
                version = "V12.0.12",
                title = "The Weather API",
                termsOfService = "http://theweatherapi.io/terms.html",
                contact = @Contact(
                   name = "Rain Moore", 
                   email = "rain.moore@theweatherapi.io", 
                   url = "http://theweatherapi.io"
                ),
                license = @License(
                   name = "Apache 2.0", 
                   url = "http://www.apache.org/licenses/LICENSE-2.0"
                )
        ),
        consumes = {"application/json", "application/xml"},
        produces = {"application/json", "application/xml"},
        schemes = {SwaggerDefinition.Scheme.HTTP, SwaggerDefinition.Scheme.HTTPS},
        tags = {
                @Tag(name = "Private", description = "Tag used to denote operations as private")
        }, 
        externalDocs = @ExternalDocs(value = "Meteorology", url = "http://theweatherapi.io/meteorology.html")
)
public interface TheWeatherApiConfig {
}

@SwaggerDefinition(
        info = @Info(
                description = "Gets the weather",
                version = "V12.0.12",
                title = "The Weather API",
                termsOfService = "http://theweatherapi.io/terms.html",
                ...
        ),
...

@SwaggerDefinition(
        info = @Info(
                ...
                contact = @Contact(
                   name = "Rain Moore", 
                   email = "rain.moore@theweatherapi.io", 
                   url = "http://theweatherapi.io"
                ),
                ...
        ),
...

@SwaggerDefinition(
        info = @Info(
                ...
                license = @License(
                   name = "Apache 2.0", 
                   url = "http://www.apache.org/licenses/LICENSE-2.0"
                )
        ),
...

...
   extensions = {
       @Extension(properties = {
           @ExtensionProperty(name = "test1", value = "value1"),
           @ExtensionProperty(name = "test2", value = "value2")
       })
    }
...

...
   "x-test1" : "value1",
   "x-test2" : "value2"
...

...
   extensions = { 
       @Extension( name = "my-extension", properties = {
           @ExtensionProperty(name = "test1", value = "value1"),
           @ExtensionProperty(name = "test2", value = "value2")
       })
    }
...

...
   "x-my-extension" : {
      "test1" : "value1",
      "test2" : "value2"
   }
...

public interface ReaderListener {

    /**
     * Called before the Swagger definition gets populated from scanned classes. Use this method to
     * pre-process the Swagger definition before it gets populated.
     *
     * @param reader the reader used to read annotations and build the Swagger definition
     * @param swagger the initial swagger definition
     */

    void beforeScan(Reader reader, Swagger swagger);

    /**
     * Called after a Swagger definition has been populated from scanned classes. Use this method to
     * post-process Swagger definitions.
     *
     * @param reader the reader used to read annotations and build the Swagger definition
     * @param swagger the configured Swagger definition
     */

    void afterScan(Reader reader, Swagger swagger);
}

public class BasePathModifier implements ReaderListener {
    void beforeScan(Reader reader, Swagger swagger){}

    void afterScan(Reader reader, Swagger swagger){
        swagger.setBasePath( System.getProperty( "swagger.basepath", swagger.getBasePath() ));
    }
}