spring boot + Swagger-ui interface documentation to write back

What is Swagger

Swagger is a framework document Restful style interface and automatically generate test online

springboot integrated swagger -ui

1 , added Swagger2 dependence of Maven

<!-- Swagger API文档 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
 <version>2.7.0</version>
</dependency>
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.7.0</version>
</dependency>

2. Create a configuration class Swagger2

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


@Configuration
EnableSwagger2 @
public  class Swagger2Config { 

    / ** 
     * swagger2 profile, here some basic configuration swagger2 content, such as packages, and so scanned 
     * 
     * @return Docket No.
      * / 
    @Bean 
    public Docket No. createRestApi () {
         return  new new Docket No. (DocumentationType. SWAGGER_2) 
                ((apiInfo)) .apiInfo 
                .Select () 
                // class in this package path, it generates the interface documentation 
                .apis (RequestHandlerSelectors.basePackage ( "com.swd.imes.web" ))
                 // add a comment ApiOperation class, it generates the interface documentation 
                .apis (RequestHandlerSelectors.withMethodAnnotation (ApiOperation. ))class 
                .paths (PathSelectors.any ()) 
                .build (); 
    } 


    / ** 
     * details function api document, here referenced note comment which 
     * 
     * @return 
     * / 
    Private ApiInfo apiInfo () {
         return  new new ApiInfoBuilder ()
                 //  // title 
                .title ( "XXX system Interface" )
                 // version number 
                .version ( "1.0" )
 //                 .termsOfServiceUrl ( "NO Terms of service")
                 // description 
                .description ( "back-office services API Interface documentation " )
                 // 作者
                .contact("程序猿  XXX ")
                 // .contact(new Contact("admin", " ", " "))
                // .license("The Apache License, Version 2.0")
                //.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }

}

@Configuration annotation, to load the class configured so Spring 
@ EnableSwagger2 annotation enabled Swagger2 
createRestApi () function creates the Bean Docket 
        select () function returns a ApiSelectorBuilder example for controlling the interface which is exposed to show Swagger to 
        use the designated scan path in this example packet defined, Swagger scans all API Controller defined at the packet, and generates a document content (except to designated @ApiIgnore). 
apiInfo () function creates basic information (basic information exhibition now pages of the document) of the Api.

3, add the contents of the document

@RestController 
@RequestMapping ( "/ IFactory / SWD / HTTP / Pack" ) 
@Api ( "Integrated Device Interface" )
 public  class DeviceIntegratedInterface { 

    @Resource 
    ILoginService iLoginService; 

    @ApiOperation (value = "Login Interface", notes = "Return Data Interface the format {\ "STATUS \": \ "true \", \ "RESULT \": \ "jSESSION logo \"} If the login is successful returns "true" and "jSESSION identity", JESSION identifies the need to preserve a global variable, each must update the value of global variables after login. " ) 
    @PostMapping ( " /equipmentIntegratedAction!logIn.action " )
     public the Result the Login ( 
            @ApiParam (value =" site "required = true) @RequestParam(value = "siteId", required = true) String siteId,
            @ApiParam(value = "用户", required = true) @RequestParam(value = "Username", required = true) String username,
            @ApiParam(value = "密码", required = true) @RequestParam(value = "Password", required = true) String password,
            @ApiParam(value = "工序", required = true) @RequestParam(value = "OPERATION", required = true) String operation,
            @ApiParam(value = "资源", required = true) @RequestParam(value = "RESOURCE", required = true) String resource,
            Request the HttpServletRequest) { 

        IF (StringUtils.isBlank (username)) {
             the throw  new new a ServiceException ( "user name can not be empty!" ); 
        } 
        IF (StringUtils.isBlank (password)) {
             the throw  new new a ServiceException ( "empty entry is not!" ); 
        } 
        IF (StringUtils.isBlank (siteId)) {
             the throw  new new a ServiceException ( "site can not be empty!" ); 
        } 

        LoginVO loginDto = new new . LoginVO () setSiteId (siteId) .setUsername (username) .setPassword (password)
                .setOperation(operation).setResource(resource).setBaseUrl(CommonUtils.getBaseUrl(request))
                .setAccessUrl(CommonUtils.getIpAddress(request));
        return ResultGenerator.genSuccessResult(iLoginService.login(loginDto));
    }

    @Resource
    ICheckOperationService iCheckOperationService;

    @ApiOperation(value = "检查是否在当前工序上排队")
    @PostMapping("/equipmentIntegratedAction!doCheckOperation.action")
    public Result doCheckOperation(
            @ApiParam(value = "json", required = true) @RequestParam(value = "dataJson") String dataJson) {

        CheckOperationVo checkOperationVo = JSON.parseObject(dataJson, CheckOperationVo.class);
        return ResultGenerator.genSuccessResult(iCheckOperationService.isCurOperationNew(checkOperationVo));
    }
}

On completion of the above code is added to start the Spring Boot program, visit: HTTP: // localhost: 8080 / Swagger-ui.html

Add annotations on the controller, auto-generated API documentation

Common notes:

@Api: with class, the role of the class described.

@ApiOperation: annotation to increase the API method explanation.

@ApiParam: a method, the parameter, field descriptions, adding metadata to represent the parameters (if required instructions or the like)

@RestController 
@RequestMapping ( " / IFactory / SWD / HTTP / Pack")
 @Api ( "Query Interface")
 public class QueryDataInterface { 

    @Resource 
    ICheckBarcodeService iCheckBarcodeService; 

    @ApiOperation (value = "cell barcode and barcode PACK peer review", notes = "single cell PackSn CellSn peer review and / multi-core CellSn any check PackSn")
     @PostMapping ( " / equipmentIntegratedAction! doCheckBarcode.action")
     public the Result doCheckBarcode ( @ApiParam (value = "JSON",required = true) @RequestParam(value = "dataJson") String dataJsonVo) {
        CheckBarcodeVo checkBarcodeVo = JSON.parseObject(dataJsonVo, CheckBarcodeVo.class);
        return ResultGenerator.genSuccessResult(iCheckBarcodeService.findCellCode(checkBarcodeVo));
    }
}

 

@ApiOperation the API and associated annotations @ApiParam added, parameters as follows: 
@ApiOperation (value = "Description Interface", httpMethod = "interface request mode", response = "return parameter Interface Type", notes = "Interface Release Notes "); other parameters refer to the source; 
@ApiParam (= required" parameter must whether ", name =" parameter name ", value =" description specific parameters ")

 

https://www.cnblogs.com/woshimrf/p/5863318.html