This is the first day of my participation in Gwen Challenge

Swagger2 introduction

API documentation is the best way to communicate in the front – and – back – end separated development model.

Swagger is a canonical and complete framework for generating, describing, invoking, and visualizing RESTful Web services.

  • Timeliness (ability to timely and accurately notify front-end and back-end developers after interface changes)
  • Normative (and ensure that the interface is normative, such as interface address, request mode, parameters, response format, and error message)
  • Consistency (The interface information is consistent, but the document version is inconsistent, resulting in differences)
  • Testability (test directly on the interface document)

Configuration file

1. Dependence:

<! --swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> < version > 2.7.0 < / version > < / dependency > < the dependency > < groupId >. IO springfox < / groupId > < artifactId > springfox swagger - UI < / artifactId > < version > 2.7.0 < / version > < / dependency >Copy the code

2. Configuration class:

@Configuration @EnableSwagger2 public class Swagger2Config { @Bean public Docket webApiConfig(){ return new Docket(DocumentationType.SWAGGER_2); }}Copy the code

3. Configure config

@configuration@enablesWagger2 Public Class Swagger2Config {/** * Web * name and filter interface. * @return */ @Bean public Docket webApiConfig(){ return new Docket(DocumentationType.SWAGGER_2).groupName("webApi") .apiInfo(webApiInfo()) .select() .paths(Predicates.and(PathSelectors.regex("/api/.*"))).build(); } /** * public Docket adminApiConfig(){return new Docket(DocumentationType.SWAGGER_2).groupName("adminApi") .apiInfo(adminApiInfo()) .select() .paths(Predicates.and(PathSelectors.regex("/admin/.*"))).build(); } private ApiInfo webApiInfo(){return new ApiInfoBuilder().title().description() Version (" 1.0 "). Contact (new contact (" xiaolei ", "https://juejin.cn/user/96412756360526", "* * * @ qq.com")). The build (); } private ApiInfo adminApiInfo(){return new ApiInfoBuilder().title(" ApiInfoBuilder ") .description(" This document describes the definition of the back-end management API interface of Xiaolei Video ").version("1.0").contact(new Contact("xiaolei","https://juejin.cn/user/96412756360526","****@qq.com")) .build(); }}Copy the code

Common notes

3.1 API model

You can add some custom Settings to the entity class of entity, such as:

@APIModelProperty (value = "enter time ",example = "2021-05-31") @jsonFormat (timeZone = "GMT+8",pattern =" YYYY-MM-DD ") private Date joinDate;Copy the code

3.2 Defining Interface Description and Parameter Description

  • @Api: Decorates the entire class to describe what Controller does
  • ApiOperation: Describes a method, or interface, of a class
  • @APIParAM: Single parameter description
  • @APIModel: Accept arguments with objects
  • ApiProperty: A field describing an object when receiving a parameter with the object
  • @apiResponse: HTTP responds to one of the descriptions
  • @apiresponses: Overall description of HTTP responses
  • @apiIgnore: Ignore the API with this annotation
  • @apiError: Information returned when an error occurs
  • ApiImplicitParam: Describes a request parameter. You can configure the Chinese meaning of the parameter and set the default value for the parameter
  • @APIIMPLICITParams: Describes a list of request parameters annotated by multiple @APIIMPLicitParam parameters
@api (description = "lecturer management ") @apiOperation (value =" delete lecturer by ID ",notes = "logical delete ")Copy the code